🎨 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

---

Made by Purple Horizons License: MIT Python 3.10+ Printful API v2

GitHub Stars GitHub Forks

---

🎁 New to Printful?

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

---

✨ Features

🎁 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

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

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

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

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

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

# 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

# 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

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

🛠️ Available Tools

🎓 Documentation

🔄 API Version Strategy

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

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

⚙️ Rate Limiting & Performance

🐛 Troubleshooting

# Check your .env file
cat .env

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

🧪 Testing

export PRINTFUL_API_KEY=your-key
python test_server.py

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

"List Printful countries"

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

📚 Resources & Links

📄 License

💝 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