Printful Mcp

🎨 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](#installation) • [🔧 Configuration](#configuration) • [🚀 Examples](#usage-examples) • [📖 Documentation](QUICKSTART.md)

---

[](https://purplehorizons.io) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://developers.printful.com/docs/v2-beta/)

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

---

🎁 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](.cursor/skills/) that automatically teaches AI assistants how to use the Printful MCP effectively. Just open the project and start asking questions!

---

🚀 Quick Start

📋 Prerequisites

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

⚡ Installation (3 steps)

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

For Cursor

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"
      }
    }
  }
}

For Claude Desktop

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.

📡 Available Transports

| 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](QUICKSTART.md) • [💬 Join Community](#)

---

🛠️ Available Tools

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

| 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?" |

📦 Order Tools (4) - Create & manage orders

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

🚚 Shipping Tools (2) - Calculate rates & delivery

| 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?" |

🖼️ Mockup Tools (2) - Generate product images

| 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?" |

📁 File Tools (2) - Upload & manage designs

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

🏪 Store Tools (2) - Manage stores & stats

| 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?" |

🔄 Sync Product Tools (2) - Legacy v1 features

| 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](QUICKSTART.md)

Get up and running in 5 minutes

🔑 [API Token Setup](APITOKENSETUP.md)

Detailed token configuration guide

🧪 [Testing Guide](TESTING.md)

Learn how to test your integration

🔐 [API Scopes Reference](APISCOPESREFERENCE.md)

Required permissions explained

💻 [Examples](examples.py)

Real code examples

🔧 [Cursor Config](cursor-mcp-config.json)

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

❌ "PRINTFULAPIKEY environment variable is required"

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 contain:
PRINTFUL_API_KEY=your-actual-key-here

⏱️ "Rate limit exceeded"

Solution: Wait for the time specified in the error message (usually 60 seconds).

• Default limit: 120 requests/minute
• Consider implementing request batching
• Check X-Ratelimit-Reset header for exact reset time

🔍 "Resource not found"

Solution: Double-check the ID you're using.

• For orders: You can use external IDs by prefixing with @ (e.g., @my-order-123)
• For products: Verify the product/variant ID exists in the catalog
• Check if the resource belongs to your store

🎨 Mockup generation stuck on "pending"

Solution: Mockup generation typically takes 10-30 seconds.

• Wait at least 30 seconds before checking status
• If stuck longer than 2 minutes, check task status - it may have failed
• Verify your design URL is publicly accessible

---

🧪 Testing

Choose Your Testing Method

⚡ Quick Test

Automated test suite

export PRINTFUL_API_KEY=your-key
python test_server.py

✅ Tests 6 core features ⏱️ Takes 30 seconds

🌐 Interactive Test

Web-based MCP Inspector

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

🎯 Test any tool visually 🌍 Opens at localhost:5173

🤖 Live Test

In Claude/Cursor

Just ask:

"List Printful countries"

💬 Natural language ✨ Real integration test

📖 Full testing guide: See [TESTING.md](TESTING.md) for comprehensive testing instructions.

---

🏗️ Project Structure

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

---

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Report Bugs

Found an issue? Open a bug report

✨ Request Features

Have an idea? Suggest a feature

🔧 Submit PRs

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push and open a Pull Request

---

📚 Resources & Links

| Resource | Link | |:--------:|:----:| | 📘 Printful API v2 Docs | developers.printful.com/docs/v2-beta | | 📗 Printful API v1 Docs | developers.printful.com/docs | | 🔌 MCP Protocol Spec | modelcontextprotocol.io | | 🐍 FastMCP Framework | github.com/modelcontextprotocol/python-sdk | | 🎨 Purple Horizons | purplehorizons.io | | 👨‍💻 Made by Gianni | giannidalerta.com |

---

📄 License

MIT License - Free to use, modify, and distribute

[View License](LICENSE) • Purple Horizons LLC • 2026

---

💝 Support This Project

If this project helped you, consider:

⭐ Star this repo on GitHub

🐦 Share it on social media

🤝 Contribute to the codebase

🎨 Sign up for Printful using our affiliate link

Made with ❤️ by Purple Horizons

Empowering businesses through AI automation

---

🚀 Ready to automate your print-on-demand business?

[Get Started Now](#installation) • [View Examples](#usage-examples) • [Read Docs](QUICKSTART.md)

Questions? Issues? Open an issue or contact us

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Purple-Horizons
• Source: Purple-Horizons/printful-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.