Printful MCP Server

🎨 打印MCP服务器

使用AI自动化您的按需打印业务

通过模型上下文协议将Printful强大的API连接到Claude、Cursor和其他人工智能助手。

📚 快速开始 • 🔧 配置 • 🚀 例子 • 📖 文档

______________________________________________________________________

   

](https://github.com/Purple-Horizons/printful-ph-mcp) ](https://github.com/Purple-Horizons/printful-ph-mcp/fork)

______________________________________________________________________

🎁 刚接触Printful？

立即开始按需打印业务•无前期成本•300多种产品•全球配送

______________________________________________________________________

✨ 特性

🎯 API全面覆盖

• ✅ 完整的打印API v2支持
• ✅ 旧功能的智能v1回退
• ✅ 所有主要领域的17个工具
• ✅ 实时库存和定价数据

🛡️ 生产就绪

• ✅ 类型安全的Pydantic验证
• ✅ 稳健的错误处理
• ✅ 费率限制管理
• ✅ 双输出格式（JSON/Markdown）

🚀 轻松集成

• ✅ 与Claude Desktop配合使用
• ✅ 适用于Cursor IDE
• ✅ stdio+HTTP传输
• ✅ 无需主机

🤖 包括AI技能

• ✅ 光标技能教AI如何使用工具
• ✅ 内置最佳实践
• ✅ 自动应用工作流
• ✅ 开箱即用的更好体验

🎁 奖金： 此回购包括 光标AI技能 它自动教AI助手如何有效地使用Printful MCP。只需打开项目并开始提问！

______________________________________________________________________

🚀 快速开始

📋 Prerequisites

• Python 3.10+ (下载)
• 打印API密钥 (免费获得一个)

⚡ Installation (3 steps)

步骤1：克隆并安装

git clone https://github.com/Purple-Horizons/printful-ph-mcp.git
cd printful-ph-mcp
pip install -e .

步骤2：设置API密钥

cp .env.example .env
# Edit .env and add: PRINTFUL_API_KEY=your-key-here

步骤3：配置您的AI助手

For Cursor

添加到 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "printful": {
      "command": "python",
      "args": ["-m", "printful_mcp"],
      "cwd": "/path/to/printful-ph-mcp",
      "env": {
        "PRINTFUL_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "printful": {
      "command": "python",
      "args": ["-m", "printful_mcp"],
      "cwd": "/path/to/printful-ph-mcp",
      "env": {
        "PRINTFUL_API_KEY": "your-api-key-here"
      }
    }
  }
}

✅ 就是这样！ 重启你的AI助手，开始使用Printful工具。

______________________________________________________________________

🔌 运输选项

默认情况下，服务器使用 标准 传输（Cursor/Claude Desktop需要）。对于HTTP客户端或mcporter等工具，您可以使用HTTP传输。

📡 Available Transports

HTTP传输示例：

# Start server on port 8000
python -m printful_mcp --transport http --port 8000

# Or with custom host
python -m printful_mcp --transport http --host 0.0.0.0 --port 8080

与mcporter一起使用：

# Option 1: Use JSON args format (recommended)
mcporter call printful_mcp.printful_list_catalog_products --args '{"limit":20}'

# Option 2: Use typed values (colon for numbers)
mcporter call printful_mcp.printful_get_product product_id:71

______________________________________________________________________

🎨 你能做什么

______________________________________________________________________

💡 用法示例

🎯 示例1：找到完美的产品

# Ask your AI assistant:
"Show me all t-shirts available for DTG printing under $15"

# It will use:
printful_list_catalog_products(
    types="T-SHIRT",
    techniques="dtg",
    limit=20,
    format="markdown"
)

💰 示例2：获取定价

# Ask your AI assistant:
"What's the price for variant 4011 in USD?"

# It will use:
printful_get_variant_prices(
    variant_id=4011,
    currency="USD",
    format="markdown"
)

📦 示例3：创建订单

# Ask your AI assistant:
"Create a draft order for John Doe at 123 Main St, Los Angeles, CA 90001"

# It will use:
printful_create_order(
    recipient_name="John Doe",
    recipient_address1="123 Main St",
    recipient_city="Los Angeles",
    recipient_state_code="CA",
    recipient_country_code="US",
    recipient_zip="90001"
)

🎨 示例4：生成产品模型

# Ask your AI assistant:
"Generate a mockup for product 71 with my design"

# It will use:
printful_create_mockup_task(
    product_id=71,
    variant_ids="4011,4012",
    design_url="https://example.com/design.png",
    placement="front"
)

🎬 想看看它的实际效果吗？

📺 观看演示视频 • 📖 阅读完整文档 • 💬 加入社区

______________________________________________________________________

🛠️ 可用工具

🛍️ Catalog Tools (5) - Browse products & check availability

📦 Order Tools (4) - Create & manage orders

🚚 Shipping Tools (2) - Calculate rates & delivery

🖼️ Mockup Tools (2) - Generate product images

📁 File Tools (2) - Upload & manage designs

🏪 Store Tools (2) - Manage stores & stats

🔄 Sync Product Tools (2) - Legacy v1 features

______________________________________________________________________

🎓 文档

📖 快速入门指南

5分钟后起床跑步

🔑 API令牌设置

详细的令牌配置指南

🧪 测试指导

了解如何测试您的集成

🔐 API范围参考

说明所需权限

💻 例子

真实代码示例

🔧 游标配置

即用配置文件

______________________________________________________________________

🔄 API版本策略

此服务器使用 打印API v2 （生产就绪测试版）带智能 v1回退:

🎯 v2（主要）

• ✅ 目录和产品
• ✅ 订单与履行
• ✅ 运费
• ✅ 模型生成
• ✅ 文件管理
• ✅ 店铺统计

🔄 v1（回退）

• ✅ 同步产品
• ✅ 产品模板
• ⚠️ 需要时自动切换
• 🚀 面向未来的架构

为什么是v2？ 更好的分页•实时库存•增强订单•提高安全性•标准化格式

______________________________________________________________________

⚙️ 速率限制和性能

📊 速率限制

• 120个请求/60秒
• 漏桶算法
• 自动重试429个错误

🚀 演出

• 响应时间：100-500ms
• 并发请求：支持
• 超时处理：内置

______________________________________________________________________

🐛 故障排除

❌ "PRINTFUL_API_KEY environment variable is required"

解决方案： 确保您的API密钥设置在 .env 或者通过MCP配置中的环境变量传递。

# Check your .env file
cat .env

# Should contain:
PRINTFUL_API_KEY=your-actual-key-here

⏱️ "Rate limit exceeded"

解决方案： 等待错误消息中指定的时间（通常为60秒）。

• 默认限制：120个请求/分钟
• 考虑实现请求批处理
• 检查 X-Ratelimit-Reset 用于精确重置时间的标头

🔍 "Resource not found"

解决方案： 仔细检查您正在使用的ID。

• 对于订单：您可以通过前缀使用外部ID @ （例如。， @my-order-123)
• 对于产品：验证产品/变体ID是否存在于目录中
• 检查资源是否属于您的商店

🎨 Mockup generation stuck on "pending"

解决方案： 模型生成通常需要10-30秒。

• 检查状态前至少等待30秒
• 如果卡住超过2分钟，请检查任务状态-它可能已失败
• 验证您的设计URL是否可公开访问

______________________________________________________________________

🧪 测试

选择您的测试方法

⚡ 快速测试

自动化测试套件

export PRINTFUL_API_KEY=your-key
python test_server.py

✅ 测试6个核心功能 ⏱️ 需要30秒

🌐 交互式测试

基于Web的MCP检查器

export PRINTFUL_API_KEY=your-key
./test-with-inspector.sh

🎯 目视测试任何工具 🌍 在本地主机上打开：5173

🤖 带电试验

在克劳德/光标

只要问：

"List Printful countries"

💬 自然语言 ✨ 真实集成测试

📖 完整测试指南： 看 测试.md 获取全面的测试说明。

______________________________________________________________________

🏗️ 项目结构

printful-ph-mcp/
├── 📁 src/
│   └── 📁 printful_mcp/
│       ├── 🐍 server.py          # FastMCP server + tool registrations
│       ├── 🔌 client.py          # API client with auth/error handling
│       ├── 📁 tools/             # Tool implementations by domain
│       │   ├── 🛍️ catalog.py    # Product browsing (5 tools)
│       │   ├── 📦 orders.py     # Order management (4 tools)
│       │   ├── 🚚 shipping.py   # Shipping rates (2 tools)
│       │   ├── 🖼️ mockups.py    # Mockup generation (2 tools)
│       │   ├── 📁 files.py      # File management (2 tools)
│       │   ├── 🏪 stores.py     # Store statistics (2 tools)
│       │   └── 🔄 sync.py       # v1 fallback (2 tools)
│       └── 📁 models/
│           └── 📋 inputs.py      # Pydantic input models
├── 📄 pyproject.toml
├── 🔐 .env.example
└── 📖 README.md

______________________________________________________________________

🤝 贡献

我们欢迎捐款！以下是您可以提供帮助的方式：

🐛 报告Bug

发现问题？ 打开错误报告

✨ 请求功能

有主意吗？ 建议功能

🔧 提交PR

1. 分叉存储库
2. 创建功能分支
3. 提交您的更改
4. 推送并打开拉取请求

______________________________________________________________________

📚 资源和链接

______________________________________________________________________

📄 许可证

MIT许可证 -免费使用、修改和分发

查看许可证 • Purple Horizons有限责任公司 • 2026

______________________________________________________________________

💝 支持这个项目

如果这个项目对你有所帮助，请考虑：

⭐ 标记此回购 在GitHub上

🐦 分享它 在社交媒体上

🤝 贡献 到代码库

🎨 注册Printful 使用我们的联盟链接

由...制作❤️ 通过 紫色地平线

*通过人工智能自动化赋予企业权力*

______________________________________________________________________

🚀 准备好自动化您的按需打印业务了吗？

立即开始 • 查看示例 • 阅读文档