Printify MCP Server Implementation

This repository houses the source code for a specialized Model Context Protocol (MCP) server designed to bridge Large Language Models (LLMs), such as Claude, with the extensive capabilities of the Printify e-commerce fulfillment platform. It translates high-level AI instructions into concrete API actions for managing inventory, designs, and sales listings.

Documentation Index

• Operational Overview
• Core Capabilities
• Prerequisites for Deployment
• Installation Procedures
• Environment Configuration
• Execution Methods
• Standard Server Launch
• Integration with Claude Desktop Client
• Containerized Deployment via Docker (Recommended)
  • Direct Docker Hub Pull
  • Docker Compose Orchestration
• Local Development Environment
• Exposed Toolset Reference
• Account and Shop Administration
• Inventory Item Management
• Catalog & Specification Handling
• Visual Asset Handling
• Internal Reference Material
• AI Prompt Utilities
• End-to-End Workflow Scenarios
• AI-Assisted Apparel Design and Listing Creation
• Modifying Established Listings
• System Architecture Details
• Primary Software Modules
• Containerization Structure
• Public Image Registry Publication
• Standalone Docker Execution
• Source Directory Layout
• Tool Interface Specification
• Debugging and Issue Resolution
• Frequent Operational Failures
• Container-Specific Diagnostics
• Runtime Tracing
• Contribution Guidelines
• Software Licensing Information

Operational Overview

The Printify MCP Gateway functions as the intermediary layer, enabling advanced generative AI assistants (like Claude) to issue commands against the Printify print-on-demand fulfillment API. This capability spans the automated creation of sellable merchandise, utilization of generative adversarial networks (GANs) for design conceptualization, and managing all facets of product lifecycles through the established Model Context Protocol (MCP) framework. MCP, pioneered by Anthropic, defines a structured method for context exchange between applications and LLMs; this server adheres to that specification to expose Printify's functional scope.

Core Capabilities

This dedicated MCP integration furnishes the following functionalities:

Printify API Interfacing

• Authorization: Secure initialization of the Printify API client utilizing an external API key.
• Shop Operations: Enumeration and administration of user-owned Printify sales storefronts.
• Product Lifecycle: Full CRUD operations (Create, Read, Modify, Decommission) and external sales channel publication for products.
• Catalog Navigation: Querying available merchandise templates (blueprints), associated fulfillment partners, and specific size/color permutations (variants).
• Asset Upload: Securely transmitting visual assets intended for product mockups.

Generative Visual Asset Pipeline

• Replicate Integration: Leveraging advanced visual models, specifically Flux 1.1 Pro, hosted on Replicate.
• Unified Workflow: A singular operation that handles AI image synthesis, post-generation processing, and direct deposition into the Printify asset library.

Support & Guidance

• Self-Contained Documentation: Full specifications for every accessible tool function are embedded within the server interface.
• Process Outlining: Provision of structured guides detailing typical product fabrication sequences.

Prompt Utilities

• Description Synthesis: Automatic drafting of persuasive marketing copy for products based on supplied structural attributes.

Prerequisites for Deployment

Deployment necessitates the following runtime components and credentials:

• Runtime Environment: Node.js (version 18 or newer)
• Package Manager: npm (version 7 or newer)
• Credentials 1: A valid Printify Developer API Key
• Credentials 2: An active API Token for the Replicate service (for image generation)
• Credentials 3: An ImgBB API Key (Mandatory only when invoking the Flux 1.1 Pro Ultra model due to large file sizes).

Installation Procedures

bash

Obtain the source repository

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

Install all required package dependencies

npm install

Compile TypeScript sources to JavaScript

npm run build

Environment Configuration

Configuration relies on environment variables, which can be supplied via two primary methods:

Option 1: Using a .env File (Recommended Practice)

1. Generate a file named .env in the project's root directory and populate it with:

Essential for all Printify operations

PRINTIFY_API_KEY=your_printify_api_key

Required if utilizing the Flux 1.1 Pro Ultra model for high-res generation

IMGBB_API_KEY=your_imgbb_api_key

Optional: Defaults to the first shop if omitted

PRINTIFY_SHOP_ID=your_shop_id

Optional: Essential only for leveraging AI image synthesis capabilities

REPLICATE_API_TOKEN=your_replicate_api_token

Use the provided template file as a starting point:

bash cp .env.example .env

Edit .env with your actual secrets

Option 2: Using System Environment Variables

Alternatively, these values can be exported directly into your operating system's environment:

Windows (Command Prompt): cmd :: Mandatory Key set PRINTIFY_API_KEY=your_printify_api_key

:: Optional Keys set PRINTIFY_SHOP_ID=your_shop_id

:: Optional - only for visual asset creation set REPLICATE_API_TOKEN=your_replicate_api_token

Windows (PowerShell): powershell

Mandatory Key

$env:PRINTIFY_API_KEY = "your_printify_api_key"

Optional Keys

$env:PRINTIFY_SHOP_ID = "your_shop_id"

Optional - only for visual asset creation

$env:REPLICATE_API_TOKEN = "your_replicate_api_token"

macOS/Linux: bash

Mandatory Key

export PRINTIFY_API_KEY=your_printify_api_key

Optional Keys

export PRINTIFY_SHOP_ID=your_shop_id

Optional - only for visual asset creation

export REPLICATE_API_TOKEN=your_replicate_api_token

The server exhaustively checks for these environment settings during its initialization phase, irrespective of whether they originate from a .env file or system scope.

Obtaining Required Credentials

Printify API Key Acquisition: 1. Access your Printify dashboard. 2. Navigate to Settings -> API section. 3. Initiate the creation of a 'New API Key'. 4. Securely copy the generated key and integrate it into your configuration file.

Replicate API Token Acquisition: 1. Register or log in at Replicate. 2. Proceed to your user account settings. 3. Generate and retrieve an API token. 4. Insert this token into the designated field within your .env configuration.

Execution Methods

Standard Server Launch

bash npm start

This command initiates the MCP gateway utilizing the standard input/output (stdio) transport mechanism, facilitating direct communication with compatible MCP clients such as Claude Desktop. The Printify client setup is automated, drawing the necessary API key from the environment variables.

Local Development Environment

bash npm run dev

Activates the server in a development context, featuring live-reloading capabilities upon source code modifications.

Using with Claude Desktop

Integration with the Claude Desktop application is supported through three deployment paradigms:

Option 1: Global npm Installation (Primary Recommendation)

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

2. Finalize environment variable setup using a local .env file or system variables, as detailed in the Configuration section.

3. Configure the server connection within Claude Desktop:

4. Open the application's Settings panel and navigate to MCP Servers.
5. Select 'Add Server'.
6. Assign a recognizable identifier (e.g., "Printify Integration").
7. Select 'Command' for the transport protocol.
8. Input printify-mcp as the command executable.
9. No additional arguments are required.

10. Confirm by clicking 'Add Server'.

11. Verify connectivity by prompting Claude to query the Printify connection status:

Can you check the status of my Printify connection?

The printify-mcp executable runs the core logic, packaged as a system-accessible command.

Option 2: Utilizing npx

If avoiding a global installation is preferred, npx offers an on-demand execution path:

1. Configure environment secrets as specified in the Configuration section.

2. Configure Claude Desktop:

3. Open Settings > MCP Servers.
4. Click 'Add Server'.
5. Name the server (e.g., "Printify MCP via npx").
6. Transport type: 'Command'.
7. Command: npx.
8. Arguments: @tsavo/printify-mcp.
9. Finalize by clicking 'Add Server'.

Option 3: Containerized Deployment via Docker (Recommended for Isolation)

For users prioritizing operational isolation via containerization, two distinct Docker pathways exist:

Option 3A: Direct Docker Hub Pull

1. Ensure Docker is installed and operational on your host system.

2. Establish a dedicated workspace directory: bash mkdir printify-mcp-docker cd printify-mcp-docker

3. Define your secrets within a local .env file:

PRINTIFY_API_KEY=your_printify_api_key PRINTIFY_SHOP_ID=your_shop_id (optional) REPLICATE_API_TOKEN=your_replicate_api_token IMGBB_API_KEY=your_imgbb_api_key (mandatory for Ultra model)

1. Allocate a subdirectory for temporary artifacts: bash mkdir temp

2. Initiate the Docker container using one of the following invocation patterns:

Pattern A: Direct Environment Variable Injection (Preferred) bash # Linux/macOS/Windows PowerShell: docker run -it --name printify-mcp \ -e PRINTIFY_API_KEY=your_printify_api_key \ -e PRINTIFY_SHOP_ID=your_shop_id_optional \ -v $(pwd)/temp:/app/temp \ tsavo/printify-mcp:latest

# Windows Command Prompt: docker run -it --name printify-mcp ^ -e PRINTIFY_API_KEY=your_printify_api_key ^ -e PRINTIFY_SHOP_ID=your_shop_id_optional ^ -v %cd%/temp:/app/temp ^ tsavo/printify-mcp:latest

Prerequisite Note: If utilizing the visual asset generation tools, include REPLICATE_API_TOKEN in the -e list. For the high-fidelity Flux 1.1 Pro Ultra model, the IMGBB_API_KEY is also required for file handling.

Pattern B: Utilizing the .env File Volume Mount bash # Linux/macOS: docker run -it --name printify-mcp \ -v $(pwd)/.env:/app/.env:ro \ -v $(pwd)/temp:/app/temp \ tsavo/printify-mcp:latest

# Windows PowerShell: docker run -it --name printify-mcp -v ${PWD}/.env:/app/.env:ro -v ${PWD}/temp:/app/temp tsavo/printify-mcp:latest

# Windows Command Prompt: docker run -it --name printify-mcp -v %cd%/.env:/app/.env:ro -v %cd%/temp:/app/temp tsavo/printify-mcp:latest

1. Configure the Claude Desktop connection:
2. Navigate to Settings > MCP Servers.
3. Add Server.
4. Name: "Printify MCP Docker".
5. Transport Type: 'Command'.
6. Command: docker.
7. Arguments: exec -i printify-mcp node dist/index.js.
8. Click 'Add Server'.

Option 3B: Build and Run with Docker Compose

1. Ensure Docker Compose is installed alongside Docker.

2. Acquire the repository source locally: bash git clone https://github.com/tsavo/printify-mcp.git cd printify-mcp

3. Set environment configurations (Choose A or B):

Method A: Direct Edit of docker-compose.yml (Recommended) Modify the environment block to expose your secrets: yaml environment: - NODE_ENV=production # Option 1: Direct setting - PRINTIFY_API_KEY=your_printify_api_key - PRINTIFY_SHOP_ID=your_shop_id_optional - REPLICATE_API_TOKEN=your_replicate_api_token - IMGBB_API_KEY=your_imgbb_api_key

Method B: Mounting the Local .env File Create a local .env file containing secrets, and uncomment the corresponding volume mount in docker-compose.yml: yaml volumes: # Option 2: Mount .env for secrets - ./.env:/app/.env:ro

1. Orchestrate the container build and startup in detached mode: bash docker-compose up -d

2. Configure Claude Desktop using the same steps as 3A, targeting the container named in docker-compose.yml.

Option 4: Direct Source Checkout and Execution

For users preferring source code modification without containerization:

1. Clone the repository and navigate into the directory: bash git clone https://github.com/tsavo/printify-mcp.git cd printify-mcp

2. Install dependencies and compile the project: bash npm install npm run build

3. Determine the absolute path to the compiled entry point (dist/index.js):

Windows Path Retrieval: cmd cd dist echo %CD%\index.js

macOS/Linux Path Retrieval: bash realpath dist/index.js

1. Configure the connection in Claude Desktop:
2. Go to Settings > MCP Servers and add a new server.
3. Name: "Local Printify MCP".
4. Transport Type: 'Command'.
5. Command: node (the Node.js executable).
6. Arguments: The full absolute path obtained in the previous step.

7. Save the configuration.

8. Keep the terminal running the server active: bash npm start

Testing the Connection

Initiate a dialogue with Claude and request a status check using the designated tool:

Can you check the status of my Printify connection?

Successful operation will result in Claude invoking the get-printify-status tool. Further testing can involve requesting a shop enumeration via list-shops.

If operational failures occur, first inspect the console output from where the server was launched, confirm environment variable integrity, ensure the server process is actively executing, and finally, validate the specified file path in the Claude Desktop configuration.

Exposed Toolset Reference

Account and Shop Administration

get-printify-status

Retrieves the current operational state of the Printify API client, including connection validation and the active default storefront.

list-shops

Returns a comprehensive registry of all associated Printify storefronts. The actively utilized shop is clearly marked.

switch-shop

Redirects subsequent API requests to a specified storefront.

Parameters: - shopId (string): Unique identifier for the destination shop.

Inventory Item Management

list-products

Fetches a paginated manifest of items listed within the current shop.

Parameters: - page (number, optional): Desired page number (Default: 1). - limit (number, optional): Maximum records per page (Default: 10).

get-product

Retrieves granular details for an individual inventory item.

Parameters: - productId (string): Unique identifier for the product.

create-product

Registers a novel product listing within the Printify catalog.

Parameters: - title (string): Designated name for the merchandise. - description (string): Marketing narrative for the item. - blueprintId (number): Identifier for the base product template. - printProviderId (number): Identifier for the chosen fulfillment vendor. - variants (array): Definitions for size/color permutations. - printAreas (object, optional): Specifies placement zones for visual assets.

update-product

Modifies the metadata or variant pricing of an existing listing.

Parameters: - productId (string): Unique identifier for the listing to revise. - title (string, optional): New product title. - description (string, optional): Revised marketing description. - variants (array, optional): Updated pricing or configuration data for variants. - printAreas (object, optional): Reassignment of print imagery locations.

delete-product

Permanently removes a listing from the Printify inventory.

Parameters: - productId (string): Identifier of the item to decommission.

publish-product

Disseminates a drafted product listing to connected external sales channels (e.g., Etsy, Shopify).

Parameters: - productId (string): Identifier of the product to push live. - publishDetails (object, optional): Specification of which fields (title, price, images) to synchronize.

Catalog & Specification Handling

get-blueprints

Enumerates the range of base product templates available in the global Printify catalog.

Parameters: - page (number, optional): Page index for catalog traversal (Default: 1). - limit (number, optional): Count of templates per page (Default: 10).

get-blueprint

Fetches the detailed specification sheet for a particular merchandise template.

Parameters: - blueprintId (string): Identifier for the template.

get-print-providers

Lists the fulfillment entities capable of producing a specified blueprint.

Parameters: - blueprintId (string): Identifier of the product template in question.

get-variants

Retrieves the complete list of purchasable configurations (size/color/style) based on template and vendor selection.

Parameters: - blueprintId (string): Identifier for the base template. - printProviderId (string): Identifier for the fulfillment source.

Visual Asset Handling

generate-and-upload-image

Performs a multi-stage operation: initiating AI generation via Replicate's Flux pipeline, applying necessary image transformation (via Sharp) for compatibility, securing upload to Printify assets, and finally, purging temporary local artifacts.

Parameters: - prompt (string): The descriptive text used to seed the image generation model. - fileName (string): The name under which the asset will be cataloged in Printify. - model (string, optional): Explicitly specify the Replicate model endpoint (e.g., "black-forest-labs/flux-1.1-pro-ultra"). - width (number, optional): Desired pixel width (Default: 1024). - height (number, optional): Desired pixel height (Default: 1024). - aspectRatio (string, optional): Overrides width/height (e.g., '16:9', '1:1'). - outputFormat (string, optional): Target file type ("jpeg", "png", "webp") (Default: "png"). - numInferenceSteps (number, optional): Iteration count for the diffusion process (Default: 25). - guidanceScale (number, optional): Classifier-free guidance weight (Default: 7.5). - negativePrompt (string, optional): Stylistic elements to avoid in the output (Default: "low quality, bad quality, sketches"). - seed (number, optional): Integer for deterministic generation. - raw (boolean, optional): Produce less filtered, more raw model output (Default: true for Flux 1.1 Pro Ultra).

Dependency Warning: This function strictly requires REPLICATE_API_TOKEN. Furthermore, use of the Flux 1.1 Pro Ultra model mandates the presence of IMGBB_API_KEY as high-resolution outputs necessitate an external intermediary uploader.

generate-image

Synthesizes a visual asset using Replicate's Flux architecture and persists it to a locally accessible file path, bypassing immediate Printify upload. This allows for manual review or alternative usage.

Parameters: - prompt (string): Textual prompt for visual synthesis. - outputPath (string): The complete filesystem path where the resulting image file should reside. - model (string, optional): Model override endpoint. - width (number, optional): Output width in pixels (Default: 1024). - height (number, optional): Output height in pixels (Default: 1024). - aspectRatio (string, optional): Ratio constraint, supersedes width/height. - outputFormat (string, optional): Desired file extension (Default: "png"). - numInferenceSteps (number, optional): Diffusion steps (Default: 25). - guidanceScale (number, optional): Guidance factor (Default: 7.5). - negativePrompt (string, optional): Elements to exclude (Default: "low quality, bad quality, sketches"). - seed (number, optional): Reproducibility control value. - raw (boolean, optional): Raw output flag (Ultra model specific).

Dependency Warning: Only the REPLICATE_API_TOKEN is required for this isolated generation function.

upload-image

Transfers a visual asset into the user's Printify storage pool. This tool flexibly accepts input from three sources: 1. Remote HTTP/HTTPS URLs (direct API ingestion). 2. Absolute paths to local files (which are automatically processed by Sharp before uploading). 3. Base64 encoded image data strings.

File Specification Notes: - Accepted formats include PNG, JPEG, and SVG. - Optimal print quality is achieved at 300 DPI for standard apparel, though 120-150 DPI is acceptable for large format items (e.g., blankets). - Uploads exceeding 5MB are advised to use URL input rather than Base64 payload.

Parameters: - fileName (string): The name assigned to the file within Printify's system. - url (string): The input source (URL, local file path, or Base64 data).

AI Prompt Utilities

generate-product-description

Creates persuasive, market-ready descriptive text for a product.

Parameters: - productName (string): The canonical name of the item. - category (string): The general product classification (e.g., "T-Shirt", "Mug"). - targetAudience (string, optional): Demographic profile for the copy's tone. - keyFeatures (string, optional): A list of crucial selling points, separated by commas.

Setting Up API Keys

Printify API Key

To unlock the core fulfillment functionalities of this MCP server, authentication via a Printify API key is mandatory. Implementation steps:

1. Access your Printify administrative portal.
2. Navigate to the profile section and locate the 'Connections' utility.
3. In the Access Tokens area, generate a new Personal Access Token.
4. Crucially, store this token immediately, as it is displayed only once upon creation.
5. Configure your environment by creating a .env file in the project's root:

PRINTIFY_API_KEY=your_api_key_here # Optional default shop assignment: # PRINTIFY_SHOP_ID=your_shop_id_here

# Required for AI asset generation: REPLICATE_API_TOKEN=your_replicate_token_here

# Required for Ultra visual model output handling: IMGBB_API_KEY=your_imgbb_api_key_here

The server dynamically initializes the Printify interface using PRINTIFY_API_KEY. If PRINTIFY_SHOP_ID is absent, the system defaults to the first registered shop.

Alternatively, direct system environment exports suffice:

bash # Windows Execution Example set PRINTIFY_API_KEY=your_api_key_here; set REPLICATE_API_TOKEN=your_replicate_token_here; set IMGBB_API_KEY=your_imgbb_api_key_here; npm start

# macOS/Linux Execution Example export PRINTIFY_API_KEY=your_api_key_here; export REPLICATE_API_TOKEN=your_replicate_token_here; export IMGBB_API_KEY=your_imgbb_api_key_here; npm start

Replicate API Token

Enabling the generative visual tools necessitates a valid Replicate API token:

1. Establish or log into your Replicate account.
2. Access the settings area specific to API credentials.
3. Produce and secure your token.
4. Integrate this token into the .env configuration file as outlined above.

ImgBB API Key

Usage of the high-fidelity Flux 1.1 Pro Ultra model mandates an ImgBB API key. This is because the Ultra model generates images exceeding the size limitations for direct base64 transmission to Printify, requiring ImgBB as a temporary storage host.

1. Register or log in at imgbb.com.
2. Navigate to the API key generation portal at api.imgbb.com.
3. Integrate the acquired key into your .env file.

End-to-End Workflow Scenarios

AI-Assisted Apparel Design and Listing Creation

This sequence demonstrates generating unique front/back graphics and publishing a complete T-Shirt product:

javascript // Phase 1: Catalog Discovery and Selection // Retrieve available base product templates get-blueprints_printify() // Assume Blueprint ID 12 (Unisex Tee) is selected

// Identify fulfillment options for the chosen template get-print-providers_printify({ blueprintId: "12" }) // Assume Print Provider ID 29 (Monster Digital) is chosen

// Determine specific purchasable permutations (size/color) get-variants_printify({ blueprintId: "12", printProviderId: "29" }) // Assume Variant IDs 18100, 18101, 18102 map to Black/S, M, L

// Phase 2: Asset Generation and Upload (Front) const frontDesignAsset = await generate-and-upload-image_printify({ prompt: "A futuristic cityscape with neon lights and tall skyscrapers, horizon city logo design", fileName: "horizon-city-front" }) // Asset ID secured: 68032b22ae74bf725ed406ec

// Phase 2b: Asset Generation and Upload (Back) const backDesignAsset = await generate-and-upload-image_printify({ prompt: "A minimalist 'Horizon City' text logo with futuristic font, suitable for the back of a t-shirt", fileName: "horizon-city-back" }) // Asset ID secured: 68032b377e36fbdd32791027

// Phase 3: Final Product Registration create-product_printify({ title: "Horizon City Skyline T-Shirt", description: "Immerse yourself in the future with this premium unisex tee. The front showcases a vibrant neon cityscape, complemented by a sleek, minimalist Horizon City emblem on the reverse.", blueprintId: 12, printProviderId: 29, variants: [ { variantId: 18100, price: 2499 }, // $24.99 { variantId: 18101, price: 2499 }, { variantId: 18102, price: 2499 } ], printAreas: { "front": { position: "front", imageId: "68032b22ae74bf725ed406ec" }, "back": { position: "back", imageId: "68032b377e36fbdd32791027" } } }) // Listing established with ID: 68032b43a24efbac6502b6f7

Modifying Established Listings

javascript // List all current listings list-products_printify()

// Inspect a specific item's details get-product_printify({ productId: "68032b43a24efbac6502b6f7" })

// Apply modifications: change title, description, and increase price for all sizes update-product_printify({ productId: "68032b43a24efbac6502b6f7", title: "PREMIUM Horizon City Skyline T-Shirt", description: "Revised description emphasizing the high-quality print and unique AI design.", variants: [ { variantId: 18100, price: 2999 }, // $29.99 { variantId: 18101, price: 2999 }, { variantId: 18102, price: 2999 } ] })

// Push updated listing data live to connected sales channels publish-product_printify({ productId: "68032b43a24efbac6502b6f7", publishDetails: { title: true, description: true, variants: true } })

// Final step: Retire the product listing delete-product_printify({ productId: "68032b43a24efbac6502b6f7" })

System Architecture Details

Primary Software Modules

1. MCP Interface (src/index.ts): The core process manager that initializes the MCP server instance and registers the specific tool functions designed for Printify interaction.
2. Printify Integration Layer (src/printify-api.ts): Encapsulates all HTTP communication and data transformation necessary to interface correctly with the external Printify REST API.
3. Generative Asset Client (src/replicate-client.ts): Manages the lifecycle of querying Replicate's inference endpoints for visual content creation.

Containerization Structure

The Docker setup is designed for portability and minimal host dependency:

1. Dockerfile: Contains instructions for building a self-contained image. It leverages a lightweight Node.js base (e.g., Alpine variant) and executes build steps (dependency installation, TypeScript compilation) before defining the final execution command.

2. docker-compose.yml: Orchestrates the service, defining how environment secrets (.env mount) and persistent storage (temp volume mount) are handled, alongside configuring essential TTY/STDIO settings for MCP transport.

3. Volumes: Runtime data persistence relies on two mapped directories: the read-only .env file for secrets and a read/write temp volume for intermediate image files.

Public Image Registry Publication

To ensure accessibility for users without local Node.js environments, the container image can be pushed to a public registry like Docker Hub:

1. Image Construction: Build the local image, tagging it for the target registry: bash docker build -t tsavo/printify-mcp:latest .

2. Registry Authentication: Secure login to the destination registry: bash docker login

3. Image Dissemination: Push the tagged image: bash docker push tsavo/printify-mcp:latest

Standalone Docker Execution

Users requiring the functionality without installing Node.js only need a functional Docker runtime. They execute the pre-built image directly:

1. Prerequisite: Docker installation.

2. Setup Local Artifact Storage: bash mkdir -p temp

3. Container Launch (Environment Variables Preferred): bash docker run -it --name printify-mcp \ -e PRINTIFY_API_KEY=their_printify_api_key \ -v $(pwd)/temp:/app/temp \ tsavo/printify-mcp:latest

(Ensure all necessary -e flags, including Replicate and ImgBB tokens if applicable, are present.)

1. Claude Desktop Configuration: The server is registered as a 'Command' transport type, executing docker exec -i printify-mcp node dist/index.js.

This method abstracts the entire Node.js runtime and build toolchain away from the end-user.

Source Directory Layout

printify-mcp/ ├── dist/ # Compiled JavaScript assets ├── docs/ # Generated Markdown documentation for tools │ ├── index.ts.md │ ├── printify-api.ts.md │ └── replicate-client.ts.md ├── src/ # Original TypeScript source files │ ├── index.ts # Primary MCP server bootstrap │ ├── printify-api.ts # Printify API wrapper │ └── replicate-client.ts # Replicate service adapter ├── temp/ # Runtime directory for synthesized images ├── .env # Localized, sensitive configuration data (ignored by Git) ├── .env.example # Template for configuration secrets ├── docker-compose.yml # Multi-container definition file ├── Dockerfile # Single-container build instructions ├── package.json # Project metadata and scripts ├── README.md # This explanatory document └── tsconfig.json # TypeScript compiler settings

Tool Interface Specification

For comprehensive technical details regarding parameter schemas and return types for each function, consult the generated Markdown documentation artifacts located in the docs/ subdirectory.

Debugging and Issue Resolution

Frequent Operational Failures

Printify Authentication Failure: Indicated by errors suggesting invalid credentials or unauthorized access. Remedy: Verify that PRINTIFY_API_KEY is correct and active in the Printify console.

Replicate Service Unreachable: Errors related to image generation failing. Remedy: Confirm REPLICATE_API_TOKEN is valid and that the target Replicate model endpoint is accessible.

Product Creation Schema Mismatch: Errors during listing creation. Remedy: Validate that blueprintId, printProviderId, and especially variantId references precisely match the catalog data retrieved by the preceding catalog tools.

Image Upload Constraints: Failures during asset transfer. Remedy: Check image file size (must be under 10MB for Base64) and ensure remote URLs are publicly linkable.

Container-Specific Diagnostics

If utilizing Docker, diagnostics shift focus to container health:

1. Container Status Check: Use docker ps to confirm the container named printify-mcp is actively running.

2. Log Inspection: The most valuable step is examining the container's standard output: bash docker logs printify-mcp

3. Configuration Mount Verification: If secrets appear missing, ensure the .env file is correctly mapped in the volume command (e.g., using $(pwd) or %cd% appropriately for the shell).

4. Connectivity from Container: Verify that the container network can reach external services if required.

Container restart procedures:

Docker Compose: bash docker-compose down docker-compose up -d

Direct docker run (Requires stop/removal first): bash docker stop printify-mcp docker rm printify-mcp

Re-run the original docker run command

For Windows PowerShell users re-running a direct container: powershell docker stop printify-mcp; docker rm printify-mcp; docker run -it --name printify-mcp -v ${PWD}/.env:/app/.env:ro -v ${PWD}/temp:/app/temp tsavo/printify-mcp:latest

Runtime Tracing

The server incorporates verbose logging to track the execution path and intermediate data structures. All errors will be outputted to the console where the server process is running. For Docker deployments, utilize docker logs -f printify-mcp to stream these updates live.

Contribution Guidelines

We welcome external feature proposals, bug reports, and code contributions via Pull Requests.

Software Licensing Information

This project is distributed under the ISC License.