内容
# mcp-printful
[](https://python.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
**MCP 服务器，用于 Printful 产品管理。** 提供 Claude 直接访问 Printful 的功能 — 上传设计、保存模板和发布产品到 WooCommerce，无需编写脚本。
构建在 [printful-cli](https://github.com/cr0hn/prinful-cli) 之上，后者作为依赖项自动安装 — 无需单独设置。对于发布后的 WooCommerce 管理（类别、描述、图片），请使用 [mcp-woocommerce](https://github.com/cr0hn/mcp-woocommerce)。
---
## 功能
| 工具 | 描述 |
|---|---|
| `upload_design` | 将设计图片上传到 Printful 文件库（通过 URL 或本地文件） |
| `get_file_info` | 获取已上传文件的详细信息，包括 thumbnail_url |
| `save_template` | 将设计保存为 Printful 产品模板 |
| `publish_to_store` | 将保存的模板发布到 WooCommerce |
| `create_product` | 完整流程：上传 → 保存模板 → 发布（一次调用） |
| `renew_session` | 检查会话状态 / 指示用户重新身份验证 |
| `list_blueprints` | 显示支持的产品类型及其限制 |
---
## 安装
安装 `mcp-printful` 也会自动安装 `printful-cli` — 无需单独步骤。
```bash
# 直接使用 uvx 运行（无需安装）
uvx --from git+https://github.com/cr0hn/mcp-printful mcp-printful
# 或永久安装
uv tool install git+https://github.com/cr0hn/mcp-printful
```
### 首次设置
安装后，一次配置您的凭证：
```bash
# Bearer token — 用于文件上传（在 developers.printful.com/tokens 获取）
printful-cli config set-token YOUR_TOKEN
# WooCommerce 商店 ID
printful-cli config set-store YOUR_STORE_ID
# 浏览器登录 — 用于保存模板和发布（打开浏览器）
printful-cli auth
```
这些存储在 `~/.config/printful-cli/` 中，并在 CLI 和 MCP 之间共享。
---
## 配置
| 变量 | 描述 | 必需 |
|---|---|---|
| `PRINTFUL_TOKEN` | Printful 开发者门户 Bearer token | 用于 `upload_design`、`get_file_info` |
会话 cookie 从 `~/.config/printful-cli/session.json` 读取（由 `printful-cli auth` 设置）。
---
## Claude Desktop 设置
```json
{
"mcpServers": {
"printful": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cr0hn/mcp-printful", "mcp-printful"],
"env": {
"PRINTFUL_TOKEN": "your_token_here"
}
}
}
}
```
### Claude 代码
```bash
claude mcp add printful \
--command uvx \
--args "--from,git+https://github.com/cr0hn/mcp-printful,mcp-printful" \
-e PRINTFUL_TOKEN=your_token_here
```
---
## 支持的蓝图
| 产品 | product_id | 尺寸 | 颜色 | WC 类别 |
|---|---|---|---|---|
| BC3001 成人男女通用 | 71 | XS–5XL | `"黑色 Heather"` / `"白色"` | chico (16), chica (17) |
| BC3001Y 儿童 | 307 | S, M, L, XL | `"黑色"` / `"白色"` | **儿童 (19) ONLY** |
| BC3001B 婴儿 | 305 | 6-12m, 12-18m, 18-24m | `"黑色"` / `"白色"` | **婴儿 (18) ONLY** |
> ⚠️ `"黑色 Heather"` 不适用于 BC3001Y 或 BC3001B — 使用 `"黑色"`。
---
## 产品流程
```
1. upload_design(url) → file_id
2. save_template(file_id, title, color, product_id) → template_id
3. publish_to_store(template_id, file_id, ...) → task_id
# 或一次性完成：
create_product(design_url, title, color, product_id, ...) → {file_id, template_id, task_id}
```
发布后，使用 **mcp-woocommerce** 验证产品是否显示以及更新类别、描述和图片。
---
## 开发
```bash
uv sync --all-groups
uv run pytest
# E2E（需要真实凭证）
PRINTFUL_TOKEN=... uv run pytest --e2e tests/e2e/ -v
```
---
## 许可证
MIT
