PrintKK MCP Server

This guide provides a complete overview of how to use PrintKK MCP, from obtaining API credentials and configuring the MCP server to finding products, uploading artwork, creating designs, and managing orders. It also includes simple example prompts, screenshots, security recommendations, and troubleshooting tips to help users quickly understand and complete the full PrintKK workflow.

PrintKK MCP Usage Guide

Official Model Context Protocol server for the PrintKK print-on-demand API. Use it with an MCP-compatible AI client to browse products, upload images, create designs, manage orders, and read PrintKK API documentation.

Requirements

• Node.js 18.14.1 or later
• A PrintKK API key and secret key from PrintKK Dashboard → Setting → API Management
• API permissions for each PrintKK module you want to use

Supported platforms: macOS, Linux, and Windows.

Setup

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "printkk": {
      "command": "npx",
      "args": ["-y", "@printkk/mcp@latest"],
      "env": {
        "PRINTKK_API_KEY": "your-api-key",
        "PRINTKK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

On Windows, use "command": "npx.cmd" if your MCP client cannot find npx. Restart or reload the MCP server after changing its configuration.

Configuration

| Variable | Required | Description | | --- | --- | --- | | PRINTKK_API_KEY | Yes | API key from the PrintKK dashboard | | PRINTKK_SECRET_KEY | Yes | Secret key used to sign requests | | PRINTKK_RECV_WINDOW | No | Request receive window in milliseconds; defaults to 5000 | | PRINTKK_READ_ONLY | No | Set the string value to "1" or "true" to expose only query and documentation tools |

Environment-variable values in MCP JSON must be strings. For read-only mode, use:

{
  "env": {
    "PRINTKK_API_KEY": "your-api-key",
    "PRINTKK_SECRET_KEY": "your-secret-key",
    "PRINTKK_READ_ONLY": "1"
  }
}

Do not use the JSON number 1 or boolean true for PRINTKK_READ_ONLY.

Available Tools

| Tool | Description | | --- | --- | | search_products | Browse the product catalog | | get_product | Get product variants and print areas | | upload_image | Upload a JPG/PNG from a local path or public HTTPS URL | | list_images | Browse uploaded images | | update_image | Update image metadata | | list_image_folders | List media-library folders | | create_image_folder | Create a media-library folder | | update_image_folder | Rename a media-library folder | | delete_image_folder | Delete a media-library folder | | create_design | Apply images to a product and create a design | | get_design | Get design details and specification codes | | get_design_task | Check an asynchronous design task | | list_designs | Browse existing designs | | create_brand_design | Create a brand design and wait for completion | | search_brand_designs | Browse brand designs and optionally return brand groups | | update_design | Update design name, tags, or keywords | | create_order | Create an unpaid order from a design specification | | get_order | Get order details and optionally check payment status | | list_orders | Browse orders by order, refund, or intercept status and date | | get_order_shipments | Get package, tracking, and item details for one or more orders; IDs are sent as a comma-separated orderIds query value | | pay_order | Pay a pending order from the PrintKK wallet | | cancel_order | Cancel a pending-payment order | | update_order_address | Update a pending-payment order address | | get_countries | Get supported shipping countries | | get_api_status | Check API availability and server time | | renew_api_key | Extend API-key validity when eligible | | read_api_docs | Read embedded API documentation by topic |

Recommended workflow:

search_products → get_product → upload_image → create_design
→ create_order → pay_order

When creating an order, use the designSpecificationCode returned by create_design or get_design, not the product code.

get_order_shipments accepts one or more numeric PrintKK order IDs. Multiple IDs are serialized as a single comma-separated query value, for example orderIds=1,2.

Read-only Mode

With PRINTKK_READ_ONLY set to "1", write tools are not exposed. The server provides only:

search_products, get_product, list_images, list_image_folders, get_design,
get_design_task, list_designs, search_brand_designs, get_order, list_orders, get_order_shipments,
get_countries, get_api_status, read_api_docs

Important Notes

• pay_order spends wallet funds and cannot be undone. Confirm the order and amount before paying.
• Orders can only be changed or canceled while their status is pendingPayment.
• Images must be JPG/JPEG/PNG and no larger than 100 MB.
• The PrintKK API rate limit is 60 requests per minute.
• Response timestamps use fixed UTC-8.
• Pre-release validation confirms get_order_shipments works for both single-order and multi-order queries, and list_orders accepts interceptStatus=intercepting and refundStatus=notRefunded filters.
• API keys can have module-specific permissions. Calls fail when the key lacks access to the requested module.
• The tool set covers all 29 operations in the bundled PrintKK OpenAPI specification; related operations may be combined into one workflow-oriented tool.
• read_api_docs provides guidance for authentication, signatures, workflows, endpoints, and field constraints.
• This server does not publish to external stores, manage Shopify/Etsy shops, or provide webhooks.

License

This project is source-available under the PrintKK Source-Available License 1.0. Only releases distributed through PrintKK-controlled or expressly designated channels are official.