🎨 Printful MCP Server

Automate Your Print-on-Demand Business with AI

Connect Printful's powerful API to Claude, Cursor, and other AI assistants through the Model Context Protocol.

📚 Quick Start • 🔧 Configuration • 🚀 Examples • 📖 Documentation

---

---

🎁 New to Printful?

Start your print-on-demand business today • No upfront costs • 300+ products • Global fulfillment

---

✨ Features

🎯 Complete API Coverage

• ✅ Full Printful API v2 support
• ✅ Smart v1 fallback for legacy features
• ✅ 17 tools across all major domains
• ✅ Real-time stock & pricing data

🛡️ Production Ready

• ✅ Type-safe Pydantic validation
• ✅ Robust error handling
• ✅ Rate limit management
• ✅ Dual output formats (JSON/Markdown)

🚀 Easy Integration

• ✅ Works with Claude Desktop
• ✅ Works with Cursor IDE
• ✅ stdio + HTTP transports
• ✅ No hosting required

🤖 AI Skill Included

• ✅ Cursor skill teaches AI how to use tools
• ✅ Best practices built-in
• ✅ Auto-applies workflows
• ✅ Better experience out of the box

🎁 Bonus: This repo includes a Cursor AI skill that automatically teaches AI assistants how to use the Printful MCP effectively. Just open the project and start asking questions!

---

🚀 Quick Start

• Python 3.10+ (Download)
• Printful API Key (Get one free)

Step 1: Clone & Install

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

Step 2: Set up API Key

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

Step 3: Configure Your AI Assistant

Add to ~/.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"
      }
    }
  }
}

Add to ~/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"
      }
    }
  }
}

✅ That's it! Restart your AI assistant and start using Printful tools.

---

🔌 Transport Options

By default, the server uses stdio transport (required for Cursor/Claude Desktop). For HTTP clients or tools like mcporter, you can use HTTP transport.

Transport	Use Case	Command
stdio (default)	Cursor, Claude Desktop	python -m printful_mcp
http	HTTP clients, mcporter	python -m printful_mcp --transport http
sse	Legacy SSE clients	python -m printful_mcp --transport sse

HTTP Transport Example:

# 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

Using with 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

---

🎨 What You Can Do

🛍️ Catalog	📦 Orders	🚚 Shipping	🖼️ Mockups	📁 Files	🏪 Stores
Browse 300+ products	Create & manage orders	Calculate rates	Generate mockups	Upload designs	View statistics
Check availability	Confirm fulfillment	List countries	Check status	Get file info	Multi-store support
Get pricing	Track orders	Delivery times	Custom placements	-	-

---

💡 Usage Examples

🎯 Example 1: Find the Perfect Product

# 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"
)

💰 Example 2: Get Pricing

# 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"
)

📦 Example 3: Create an Order

# 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"
)

🎨 Example 4: Generate Product Mockups

# 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"
)

🎬 Want to see it in action?

📺 Watch Demo Video • 📖 Read Full Documentation • 💬 Join Community

---

🛠️ Available Tools

Tool	Description	Example Use
printful_list_catalog_products	Browse 300+ products with filters	"Show me all hoodies"
printful_get_product	Get detailed product info	"Tell me about product 71"
printful_get_product_variants	Get all sizes/colors	"What sizes are available?"
printful_get_variant_prices	Get pricing by currency	"How much in EUR?"
printful_get_product_availability	Check stock status	"Is this in stock?"

Tool	Description	Example Use
printful_create_order	Create draft order	"Create order for John"
printful_get_order	View order details	"Show me order #12345"
printful_confirm_order	Start fulfillment	"Confirm this order"
printful_list_orders	List all orders	"Show my recent orders"

Tool	Description	Example Use
printful_calculate_shipping	Get shipping rates & times	"How much to ship to UK?"
printful_list_countries	List supported countries	"What countries do you ship to?"

Tool	Description	Example Use
printful_create_mockup_task	Generate mockup images	"Create mockup with my design"
printful_get_mockup_task	Check generation status	"Is my mockup ready?"

Tool	Description	Example Use
printful_add_file	Upload design file	"Upload my logo"
printful_get_file	Get file info & status	"Check file #12345"

Tool	Description	Example Use
printful_list_stores	List your stores	"Show all my stores"
printful_get_store_stats	View sales & profit	"What are my sales?"

Tool	Description	Example Use
printful_list_sync_products	List synced products	"Show my Etsy products"
printful_get_sync_product	Get sync product details	"Details on sync #123"

---

🎓 Documentation

📖 Quick Start Guide

Get up and running in 5 minutes

🔑 API Token Setup

Detailed token configuration guide

🧪 Testing Guide

Learn how to test your integration

🔐 API Scopes Reference

Required permissions explained

💻 Examples

Real code examples

🔧 Cursor Config

Ready-to-use config file

---

🔄 API Version Strategy

This server uses Printful API v2 (production-ready beta) with smart v1 fallback:

🎯 v2 (Primary)

• ✅ Catalog & Products
• ✅ Orders & Fulfillment
• ✅ Shipping Rates
• ✅ Mockup Generation
• ✅ File Management
• ✅ Store Statistics

🔄 v1 (Fallback)

• ✅ Sync Products
• ✅ Product Templates
• ⚠️ Auto-switches when needed
• 🚀 Future-proof architecture

Why v2? Better pagination • Real-time stock • Enhanced orders • Improved security • Standardized formats

---

⚙️ Rate Limiting & Performance

📊 Rate Limits

• 120 requests / 60 seconds
• Leaky bucket algorithm
• Auto-retry on 429 errors

🚀 Performance

• Response times: 100-500ms
• Concurrent requests: Supported
• Timeout handling: Built-in

---

🐛 Troubleshooting

Solution: Make sure your API key is set in .env or passed via environment variables in the MCP config.

# Check your .env file
cat .env

# Should cont