Printful

You can automate your Printful workflows by running a Python-based MCP server that exposes Printful API endpoints to AI assistants. This server implements the Model Context Protocol (MCP), enabling tools for catalogs, orders, shipping, mockups, files, and stores to be called by AI agents like Cursor and Claude Desktop. It provides real-time data access, type-safe validation, and error handling to help you build automated print-on-demand workflows with AI assistance.

How to use

You will run the MCP server locally and connect it to your AI assistant. The server exposes a set of tools that let you browse your catalog, check prices, create and manage orders, generate mockups, upload files, and view store statistics. Start by launching the MCP server, then configure your AI client to communicate with it using the stdio transport. Once connected, you can ask your AI assistant to perform common tasks such as finding products within a budget, retrieving pricing for a variant, or creating a draft order. The tools will translate your natural language requests into API calls behind the scenes, returning structured results for your AI to present.

How to install

Prerequisites: You need Python 3.10 or newer and a Printful API key. Install the MCP server, then run it locally so your AI assistant can connect via stdio transport.

# Step 1: Clone the project
git clone https://github.com/Purple-Horizons/printful-ph-mcp.git
cd printful-ph-mcp

# Step 2: Install the package in editable mode
pip install -e .

# Step 3: Set up your API key
cp .env.example .env
# Edit .env and add: PRINTFUL_API_KEY=your-key-here

Configuration and running the MCP server

The MCP server runs locally via Python and is configured to receive your Printful API key. You will start the server in stdio mode so your AI assistant can connect through the standard input/output channel.

# Start the MCP server in stdio mode (default)
python -m printful_mcp

Connect your AI client

Configure your AI client to talk to the local MCP server using the stdio transport. Use the standard command shown above and ensure the environment variable for the API key is set.

Usage patterns

• Find products within a budget: ask your AI to list catalog items under a price and filter by type or technique. The assistant will call printful_list_catalog_products with appropriate filters.

Examples of common tasks

• Retrieve product details, variant options, and pricing to compare items before ordering.

• Create a draft order with recipient details and delivery information.

Notes on transport and deployment

By default, the MCP server uses the stdio transport for local development. If you need HTTP, you may configure an HTTP transport in your client, but this requires a server URL that is not provided in this setup.

Troubleshooting tips

If you encounter issues with API keys or rate limits, verify that PRINTFUL_API_KEY is correctly set in your environment and that the key has the necessary permissions. If you see rate limit messages, wait as indicated and retry.

Examples of real-world flows

• A designer asks for a mockup: your AI client requests a mockup task, the server generates a mockup and returns the status.

Security considerations

Keep your Printful API key secure. Do not embed keys in code published to public repositories. Use environment variables to load keys into the MCP server process.

What you can do next

Experiment with catalog browsing, pricing checks, order creation, mockups, file uploads, and store statistics. As you grow your automation, add more AI-driven workflows that combine these capabilities to streamline your print-on-demand operations.

Available tools

printful_list_catalog_products

Browse 300+ products with filters to find items suitable for your needs.

printful_get_product

Get detailed information about a specific product.

printful_get_product_variants

Retrieve all sizes and color variants available for a product.

printful_get_variant_prices

Fetch pricing for a specific variant in a given currency.

printful_get_product_availability

Check stock status for a product or variant.

printful_create_order

Create a draft order with customer details and shipping information.

printful_get_order

View the details of a specific order.

printful_confirm_order

Start the fulfillment process for an order.

printful_list_orders

List recent or all orders for your store.

printful_calculate_shipping

Calculate shipping rates and delivery times to a destination.

printful_list_countries

List countries supported for shipping.

printful_create_mockup_task

Generate mockup images for a product with a design.

printful_get_mockup_task

Check the status of a mockup generation task.

printful_add_file

Upload a design file to the store.

printful_get_file

Retrieve information about an uploaded file.

printful_list_stores

List your Printful stores.

printful_get_store_stats

View sales and profit statistics for your stores.

printful_list_sync_products

List legacy v1 synced products.

printful_get_sync_product

Get details for a synced v1 product.