Printful MCP Server
RitikKadyan/printful-mcp-server
Automação completa de criação de produtos Printful via MCP e CLI
Ver no GitHubServidor MCP que permite a agentes de IA criar produtos end-to-end na loja Printful: buscar no catálogo, fazer upload de artes, gerar mockups e criar produtos sincronizados. Funciona como servidor MCP ou CLI, envolvendo a API v1 do Printful com camada de verificação.
Instalação
npx convez-ai RitikKadyan/printful-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de criação de produtos de print-on-demand em loja Printful
- Geração e previsualizações de mockups de designs em produtos
- Busca e validação de designs antes de sincronizar produtos
Veredito

Ferramenta técnica bem-estruturada que resolve integração real com Printful. Útil para quem opera e-commerce de POD, mas requer API token e compreensão do fluxo de upload de arquivos.
README
A tradução para o português deste README ainda está na fila.
printful-mcp-server
An MCP server (and matching CLI) that lets an AI agent create products in your Printful store end to end — search the blank catalog, upload artwork, render mockups, and create a sync product. There is no official Printful MCP connector, so this wraps Printful's v1 Products API directly.
It ships two entry points over one shared, verified API layer
(printful_create.py):
printful_mcp.py— an MCP server (stdio) for use inside Claude Code or any MCP client.printful_create.py— the same logic as a standalone CLI that prints JSON.
MCP tools
| Tool | What it does |
|---|---|
whoami | Verify the token and show which store it points at (GET /stores). |
catalog_search | Search Printful's blank-product catalog by keyword. |
product_variants | List every color/size variant (and variant_id) for a product. |
upload_design | Upload a local image file → public URL (hosted on catbox.moe). |
validate_design | Check a print-file URL is public, an image, and high-res enough. |
upload_and_validate | Upload a local file and validate it in one step. |
generate_mockup | Render a preview of the art on the product. |
create_product | Create a sync product (POST /store/products); dry-run by default. |
Requirements
- Python 3.10+
- A Printful API token (Printful Dashboard → Settings → Developers → API → Add private token). A store-level token is simplest.
pip install "mcp[cli]" requests(and optionallypillowfor the design-resolution check)
Setup
-
Copy the env template and add your token:
cp .env.example .env # edit .env and paste your token after PRINTFUL_TOKEN=.envis gitignored and never committed. Only setPRINTFUL_STORE_IDif you use an account-level token (store-level tokens don't need it). -
Verify auth:
python printful_create.py whoami
Use as an MCP server in Claude Code
Register the server (run from this directory):
claude mcp add printful -- python /absolute/path/to/printful_mcp.py
The server reads PRINTFUL_TOKEN from .env in its working directory at
startup. After changing the token, restart/reconnect the server (/mcp) so it
picks up the new value.
The flow
- Design — generate or supply artwork. Printful fetches print files by URL, so a local file must be hosted first (
upload_designdoes this for you). - Pick a product —
catalog_search→ productid. - Pick variants —
product_variants→ thevariant_ids you want (sizes/colors). - Validate —
validate_designon the print-file URL (orupload_and_validatefor a local file). - Preview —
generate_mockupto see the art on the product. - Create —
create_product(dry-run first to inspect the exact payload, thendry_run=Falseto go live).
CLI equivalent
python printful_create.py catalog-search --query "unisex t-shirt"
python printful_create.py product-variants --product-id 71
python printful_create.py validate-design --url https://.../art.png
python printful_create.py create --spec product_spec.json --dry-run
See README_printful_flow.md for the full CLI flow,
the spec-file format, and gotchas.
Notes & gotchas
- A public URL is mandatory for the print file — the #1 cause of failures. Validate before creating.
- Token scope. Store-level token → no store header. Account-level token → set
PRINTFUL_STORE_ID. - Store type. The Products API creates products in a Printful "Manual order / API" store. Shopify/WooCommerce-backed stores sync through the platform instead.
- Print resolution. Aim for ~150 DPI at printed size (often 1500px+ on the short edge); the validator warns on small files.
- Variant cap. Max 100 variants per sync product.
Security
The token is read from the environment / .env only — never hard-coded, logged,
or sent anywhere but Printful. Don't commit .env or paste your token into chat.
License
Source: Printful API v1 Products API