AI导哈

按需印刷自动化服务

Printful MCP Server是一个通过Model Context Protocol将Printful API与AI助手（如Claude和Cursor）连接的工具，提供按需印刷业务的自动化解决方案。

  • by Purple-Horizons
  • Python
  • 本地部署
  • 32 星标
  • 更新于
在 GitHub 查看 Purple-Horizons/printful-mcp

使用说明

🎨 打印MCP服务器

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

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

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

🎁 刚接触Printful？

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

✨ 特性

🎯 API全面覆盖

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

🛡️ 生产就绪

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

🚀 轻松集成

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

🤖 包括AI技能

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

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

🚀 快速开始

📋 Prerequisites
⚡ 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
运输 用例 命令
标准 （默认） 光标，克劳德桌面 python -m printful_mcp
超文本传输协议 HTTP客户端，mcporter python -m printful_mcp --transport http
SSE 传统SSE客户 python -m printful_mcp --transport sse

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

🎨 你能做什么

🛍️ 目录 📦 订单 🚚 运输 🖼️ 实体模型 📁 文件 🏪 商店
浏览300多种产品 创建和管理订单 计算价格 生成模型 上传设计 查看统计数据
检查可用性 确认履行情况 列出国家/地区 检查状态 获取文件信息 多店支持
获取定价 跟踪订单 交货时间 自定义放置 - -

💡 用法示例

🎯 示例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
工具 说明 示例使用
printful_list_catalog_products 浏览300+带滤镜的产品 “显示所有连帽衫”
printful_get_product 获取详细的产品信息 “告诉我产品71”
printful_get_product_variants 获取所有尺寸/颜色 “有哪些尺寸可供选择？”
printful_get_variant_prices 按货币获取定价 “欧元多少钱？”
printful_get_product_availability 检查库存状态 “这有库存吗？”
📦 Order Tools (4) - Create & manage orders
工具 说明 示例使用
printful_create_order 创建订单草稿 “为John创建订单”
printful_get_order 查看订单详情 “显示订单#12345”
printful_confirm_order 开始履行 “确认此订单”
printful_list_orders 列出所有订单 “显示我最近的订单”
🚚 Shipping Tools (2) - Calculate rates & delivery
工具 说明 示例使用
printful_calculate_shipping 获取运费和时间 “运往英国需要多少钱？”
printful_list_countries 列出支持的国家/地区 “您向哪些国家发货？”
🖼️ Mockup Tools (2) - Generate product images
工具 说明 示例使用
printful_create_mockup_task 生成模型图像 “用我的设计创建模型”
printful_get_mockup_task 检查生成状态 “我的模型准备好了吗？”
📁 File Tools (2) - Upload & manage designs
工具 说明 示例使用
printful_add_file 上传设计文件 “上传我的徽标”
printful_get_file 获取文件信息和状态 “检查文件#12345”
🏪 Store Tools (2) - Manage stores & stats
工具 说明 示例使用
printful_list_stores 列出您的店铺 “显示我的所有店铺”
printful_get_store_stats 查看销售额和利润 “我的销售额是多少？”
🔄 Sync Product Tools (2) - Legacy v1 features
工具 说明 示例使用
printful_list_sync_products 列出已同步的产品 “显示我的Etsy产品”
printful_get_sync_product 获取同步产品详细信息 “同步#123的详细信息”

🎓 文档

📖 快速入门指南

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. 推送并打开拉取请求

📚 资源和链接

资源 链接
📘 打印API v2文档 developers.printful.com/docs/v2-beta
📗 打印API v1文档 developers.printful.com/docs
🔌 MCP协议规范 模型上下文协议.io
🐍 FastMCP框架 github/modelcontextprotocol/python-sdk
🎨 紫色地平线 紫色
👨‍💻 由Gianni制作 giannidalerta.com

📄 许可证

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

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

💝 支持这个项目

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

⭐ 标记此回购 在GitHub上

🐦 分享它 在社交媒体上

🤝 贡献 到代码库

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




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

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

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

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

问题？问题？ 打开一个问题 或 联系我们

相关 MCP