Printify AI Integration Conduit

This document outlines the structure and functionality of the Printify Model Context Protocol (MCP) server, designed to empower Artificial Intelligence entities (like Claude) with programmatic access to Printify's extensive print-on-demand services. It adheres to the MCP standard for structured tool interaction.

Table of Contents

• High-Level Summary
• Core Capabilities
• System Requirements
• Deployment Instructions
• Local Environment Setup
• Configuration Parameters
• Execution Modes
• Standard Server Launch
• Development Workflow Launch
• Integration with Claude Desktop
• Containerized Execution (Docker)
  • Direct Image Pull
  • Docker Compose Orchestration
• Exposed Agent Tools (Tool Reference)
• Inventory and Shop Administration
• Merchandise Lifecycle Management
• Catalog Discovery (Blueprints & Providers)
• Asset Pipeline (Image Handling)
• Informational Utilities
• Complex Workflow Schemas
• AI-Powered Custom Apparel Creation
• System Blueprint
• Tool Specification Reference
• Error Resolution and Debugging
• Contribution Guidelines
• Licensing Details

High-Level Summary

The Printify AI Integration Conduit acts as a secure intermediary layer. It translates high-level AI instructions into concrete API calls against Printify's backend. Key functionality includes automated design creation via external generative models (Replicate), asset upload management, and end-to-end management of product listings.

Core Capabilities

Printify Service Interfacing

• Credential Handling: Secure initialization of the Printify REST client using API credentials.
• Shop Operations: Retrieval, listing, and context switching across affiliated merchant storefronts.
• Product Lifecycle: Full CRUD operations for merchandise items, including specification of variants and print placements.
• Catalog Exploration: Access to Printify's product catalog (blueprints) and associated fulfillment partners.
• Media Ingestion: Secure uploading of design graphics into the Printify asset repository.

Generative Design Integration

• Replicate Model Invocation: Direct integration with advanced image synthesis pipelines (specifically Flux 1.1 Pro).
• Automated Asset Pipeline: Orchestrates generation, format processing (via Sharp), secure upload to Printify, and resource cleanup.

Documentation and Assistance

• Self-Documenting Tools: Provides immediate access to parameter definitions for all functions.
• Descriptive Generation: Tool for creating persuasive, SEO-friendly product narratives.

System Requirements

• Runtime Environment: Node.js (version 18 or newer is mandated).
• Package Manager: npm (version 7 or newer).
• Access Credentials: Valid Printify Personal Access Token.
• Optional Image Synthesis: Replicate API Token.
• Mandatory for Ultra Image Generation: ImgBB API key for handling large image artifacts.

Deployment Instructions

Local Environment Setup

bash

Obtain source code repository

git clone https://github.com/tsavo/printify-mcp.git cd printify-mcp

Install required packages

npm install

Compile TypeScript source to JavaScript

npm run build

Configuration Parameters

The server requires specific environment variables to function. Configuration is managed via two primary methods:

Method A: Environment File (.env) - Preferred

Create a .env file in the root directory and populate it:

properties

Essential for API operations

PRINTIFY_API_KEY=your_printify_api_key

Required only when utilizing AI image generation capabilities

REPLICATE_API_TOKEN=your_replicate_api_token

Required ONLY when using Flux 1.1 Pro Ultra (due to size constraints needing intermediary hosting)

IMGBB_API_KEY=your_imgbb_api_key

Optional: Specify a default shop context; otherwise, the first available shop is used.

PRINTIFY_SHOP_ID=your_shop_id

Use the provided template: bash cp .env.example .env

Edit .env subsequently

Method B: System Environment Variables

Set variables directly in the operating system shell prior to execution:

Linux/macOS: bash export PRINTIFY_API_KEY=your_printify_api_key export REPLICATE_API_TOKEN=your_replicate_api_token

... set others

npm start

The server prioritizes environment variables loaded from the shell over those potentially defined in a .env file if both are present.

Credential Acquisition Guidance

• Printify API Key: Access your Printify developer settings to generate a new Personal Access Token.
• Replicate Token: Obtainable from your Replicate user settings panel.
• ImgBB Key: Secure a key from the ImgBB API dashboard; this is necessary for handling large output files from the highest fidelity AI models.

Execution Modes

Standard Server Launch

Initiates the server utilizing the standard input/output (stdio) transport channel, suitable for direct interaction with MCP-aware clients like Claude Desktop.

bash npm start

Development Workflow Launch

Starts the server with hot-reloading capabilities, ideal for active codebase modification.

bash npm run dev

Integration with Claude Desktop

AI agents interact with this server via the 'Command' transport mechanism. Choose one of the following setups:

Option 1: Global Package Installation (Recommended for Desktop)

1. Install globally: bash npm install -g @tsavo/printify-mcp

2. In Claude Desktop Settings -> MCP Servers:

3. Name: Printify Conduit
4. Transport: Command
5. Command: printify-mcp
6. Arguments: (Leave blank)

Option 2: Using NPX

1. In Claude Desktop Settings -> MCP Servers:
2. Transport: Command
3. Command: npx
4. Arguments: @tsavo/printify-mcp

Option 3: Containerized Execution (Docker) - Recommended for Isolation

This decouples the server from the host Node.js installation.

Direct Image Pull

1. Ensure Docker is running.
2. Execute the container, passing required environment variables directly (or mount a local .env file):

Linux/macOS Example (Direct Env Vars): bash docker run -it --rm --name printify-mcp-run -e PRINTIFY_API_KEY=... -v $(pwd)/temp:/app/temp tsavo/printify-mcp:latest

(Remember to include REPLICATE_API_TOKEN and IMGBB_API_KEY if image generation is required.)

1. In Claude Desktop Settings -> MCP Servers:
2. Transport: Command
3. Command: docker
4. Arguments: exec -i printify-mcp-run node dist/index.js

Docker Compose Orchestration

1. Clone the repository and edit docker-compose.yml to define credentials within the environment block (or mount a local .env file).

2. Launch the stack: bash docker-compose up -d

3. Configure Claude Desktop identically to the direct pull method, pointing to the container name printify-mcp.

Option 4: Source Repository Execution (For Developers)

1. Clone and build (see Local Setup).
2. Configure environment variables.
3. Determine the absolute path to the compiled entry point (dist/index.js).
4. In Claude Desktop:
5. Command: node
6. Arguments: /absolute/path/to/printify-mcp/dist/index.js
7. Execute npm start in the repository directory to keep the process active.

Exposed Agent Tools (Tool Reference)

Inventory and Shop Administration

• get-printify-status: Verifies API connectivity and reports the current operational shop context.
• list-shops: Enumerates all associated Printify retail locations.
• switch-shop: Re-scopes subsequent operations to a specified merchant location.
  • Parameters: shopId (String).

Merchandise Lifecycle Management

• list-products: Fetches paginated listings of existing merchandise.
  • Parameters: page (Number, default 1), limit (Number, default 10).
• get-product: Retrieves detailed attributes for a singular item.
  • Parameters: productId (String).
• create-product: Provisions a new item within the selected shop, requiring detailed specifications.
  • Parameters: title (String), description (String), blueprintId (Number), printProviderId (Number), variants (Array), printAreas (Object, optional).
• update-product: Modifies existing product attributes, pricing, or variant configurations.
  • Parameters: productId (String), plus optional update fields.
• delete-product: Permanently removes a product listing.
  • Parameters: productId (String).
• publish-product: Pushes the internal product definition live to connected sales channels.
  • Parameters: productId (String), publishDetails (Object).

Catalog Discovery (Blueprints & Providers)

• get-blueprints: Browses the master list of purchasable product templates.
  • Parameters: page (Number, default 1), limit (Number, default 10).
• get-blueprint: Fetches specifications for a single product template.
  • Parameters: blueprintId (String).
• get-print-providers: Identifies fulfillment partners capable of producing a specific blueprint.
  • Parameters: blueprintId (String).
• get-variants: Maps potential product variations (size, color) to specific pricing tiers based on provider selection.
  • Parameters: blueprintId (String), printProviderId (String).

Asset Pipeline (Image Handling)

• generate-and-upload-image: Integrated Synthesis & Ingestion Tool. Executes a prompt through Replicate's generative model, resizes/formats the output using Sharp, uploads the result to Printify, and cleans up temporary artifacts.

  • Parameters: prompt (String), fileName (String), plus extensive optional parameters for generative control (model, width, height, aspectRatio, seed, etc.).
  • Prerequisite Note: Requires both REPLICATE_API_TOKEN and, for Ultra models, IMGBB_API_KEY.

• generate-image: Local Synthesis Only. Creates an image via Replicate and saves it to a specified local path without interacting with Printify.

  • Parameters: prompt (String), outputPath (String), plus generative control options.

• upload-image: Ingests a graphic asset into the Printify media library.

  • Supports input via HTTP/HTTPS URL, local file system path, or inline Base64 data.
  • Parameters: fileName (String), url (String containing URL, path, or Base64 data).

Informational Utilities

• generate-product-description: Leverages the LLM capabilities to draft high-quality marketing copy based on input specifications.
  • Parameters: productName (String), category (String), optional targetAudience and keyFeatures.

Complex Workflow Schemas

AI-Powered Custom Apparel Creation

This sequence demonstrates chaining asset generation with product provisioning:

javascript // 1. Identify suitable base product (e.g., T-Shirt ID 12, Provider ID 29) // ... (use get-blueprints and get-print-providers)

// 2. Define design concepts for both sides const front_design = await generate-and-upload-image_printify_automation_adapter({ prompt: "Cyberpunk samurai warrior silhouette against a rainy neon city", fileName: "samurai-front-design", aspectRatio: '1:1' });

const back_logo = await generate-and-upload-image_printify_automation_adapter({ prompt: "Minimalist Kanji for 'Honor' in a bold, distressed font", fileName: "honor-back-logo" });

// 3. Construct the final item specifications using acquired Image IDs and variant data const final_product_spec = { title: "Cybernetic Honor Tee", description: "Premium unisex apparel featuring exclusive AI-generated artwork on the front and a thematic Kanji design on the reverse.", blueprintId: 12, printProviderId: 29, variants: [ { variantId: 18100, price: 2850 }, // Example mapping // ... other variants ], printAreas: { "front_placement": { position: "front", imageId: front_design.imageId }, "rear_branding": { position: "back", imageId: back_logo.imageId } } };

// 4. Finalize creation create-product_printify_automation_adapter(final_product_spec);

System Blueprint

The architecture is composed of three interacting software modules:

1. MCP Interface Layer: Manages the Model Context Protocol communication stream (stdio transport).
2. Printify Orchestrator: A dedicated module encapsulating all logic for authenticating with and manipulating the Printify API.
3. Generative Wrapper: Interfaces with external AI services (Replicate) and local asset manipulation utilities (Sharp).

Containerization leverages Node.js 22 Alpine, optimizing image size while ensuring robust runtime execution.

Tool Specification Reference

Comprehensive documentation for every available function, including mandatory and optional input schemas, can be accessed via the self-documenting nature of the MCP specification embedded within the server itself. Consult the docs/ subdirectory for static markdown exports of these specifications.

Error Resolution and Debugging

When operational failures occur, the primary diagnostic step is analyzing the console output from the active server process (use docker logs -f for containerized instances).

Common Failures & Checks

• Authentication Failure: Validate PRINTIFY_API_KEY presence and validity.
• Image Generation Stalled: Verify REPLICATE_API_TOKEN and check for IMGBB_API_KEY if using high-res models.
• Product Creation Rejection: Confirm that blueprintId, printProviderId, and all corresponding variantId mappings are current and correctly associated.
• Docker Context Issues: Verify volume mounts (-v flags or docker-compose.yml) correctly link configuration files (.env) and temporary storage (temp) to the container paths (/app/.env:ro, /app/temp).

Contribution Guidelines

We welcome pull requests that enhance functionality, improve robustness, or optimize performance.

Licensing Details

This project is released under the ISC License.

---

Reference: The underlying principles of asynchronous data transfer often mirror concepts utilized by XMLHttpRequest (XHR) in web development, enabling non-blocking communication with remote services.