convez.ai
MCP ServerIntegração & APIsIntermediário
RitikKadyan

Printful MCP Server

RitikKadyan/printful-mcp-server

Automação completa de criação de produtos Printful via MCP e CLI

Ver no GitHub
InicialPluginScore · de 0 a 100

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

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

ToolWhat it does
whoamiVerify the token and show which store it points at (GET /stores).
catalog_searchSearch Printful's blank-product catalog by keyword.
product_variantsList every color/size variant (and variant_id) for a product.
upload_designUpload a local image file → public URL (hosted on catbox.moe).
validate_designCheck a print-file URL is public, an image, and high-res enough.
upload_and_validateUpload a local file and validate it in one step.
generate_mockupRender a preview of the art on the product.
create_productCreate 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 optionally pillow for the design-resolution check)

Setup

  1. Copy the env template and add your token:

    cp .env.example .env
    # edit .env and paste your token after PRINTFUL_TOKEN=
    

    .env is gitignored and never committed. Only set PRINTFUL_STORE_ID if you use an account-level token (store-level tokens don't need it).

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

  1. Design — generate or supply artwork. Printful fetches print files by URL, so a local file must be hosted first (upload_design does this for you).
  2. Pick a product — catalog_search → product id.
  3. Pick variants — product_variants → the variant_ids you want (sizes/colors).
  4. Validate — validate_design on the print-file URL (or upload_and_validate for a local file).
  5. Preview — generate_mockup to see the art on the product.
  6. Create — create_product (dry-run first to inspect the exact payload, then dry_run=False to 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

MIT


Source: Printful API v1 Products API

Ver o original no GitHub

Bom para

Relacionados