Which integrations are available for this server?

Enables the listing and retrieval of product details for items synced from Etsy stores using Printful's legacy sync product tools.

How do I use Printful MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Printful MCP Server List all available t-shirts that support DTG printing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🎨 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

GitHub Stars GitHub Forks

🎁 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
✅ Local execution (stdio)
✅ 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.

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

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

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

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

Fork the repository
Create your feature branch
Commit your changes
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 • 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

Empowering businesses through AI automation

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

Get Started Now • View Examples • Read Docs

Questions? Issues? Open an issue or contact us