# Printify Mcp

> A Model Context Protocol (MCP) server for integrating AI assistants with Printify's print-on-demand platform

- **Type:** MCP server
- **Install:** `agentstack add mcp-tsavo-printify-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TSavo](https://agentstack.voostack.com/s/tsavo)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** ISC
- **Upstream author:** [TSavo](https://github.com/TSavo)
- **Source:** https://github.com/TSavo/printify-mcp

## Install

```sh
agentstack add mcp-tsavo-printify-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Printify MCP Server

A Model Context Protocol (MCP) server for integrating AI assistants with Printify's print-on-demand platform.

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Starting the Server](#starting-the-server)
  - [Using with Claude Desktop](#using-with-claude-desktop)
  - [Using with Docker](#option-3-use-docker-recommended-for-isolation)
    - [Docker Hub Image](#option-3a-use-the-docker-image-directly-from-docker-hub)
    - [Docker Compose](#option-3b-build-and-run-with-docker-compose)
  - [Development Mode](#development-mode)
- [Available Tools](#available-tools)
  - [Shop Management](#shop-management)
  - [Product Management](#product-management)
  - [Blueprint and Variant Management](#blueprint-and-variant-management)
  - [Image Management](#image-management)
  - [Documentation](#documentation)
  - [Prompts](#prompts)
- [Workflow Examples](#workflow-examples)
  - [Creating a T-Shirt with AI-Generated Design](#creating-a-t-shirt-with-ai-generated-design)
  - [Managing Existing Products](#managing-existing-products)
- [Architecture](#architecture)
  - [Main Components](#main-components)
  - [Docker Architecture](#docker-architecture)
  - [Publishing the Docker Image](#publishing-the-docker-image)
  - [Using the Docker Image Without Node.js](#using-the-docker-image-without-nodejs)
  - [File Structure](#file-structure)
- [API Documentation](#api-documentation)
- [Troubleshooting](#troubleshooting)
  - [Common Issues](#common-issues)
  - [Docker-Specific Issues](#docker-specific-issues)
  - [Debugging](#debugging)
- [Contributing](#contributing)
- [License](#license)

## Overview

The Printify MCP Server is a bridge between AI assistants (like Claude) and Printify's print-on-demand platform. It allows AI assistants to create and manage print-on-demand products, generate designs using AI, and handle all aspects of product management through the Model Context Protocol (MCP).

MCP is an open standard developed by Anthropic that standardizes how applications provide context to Large Language Models (LLMs). This server implements the MCP specification to expose Printify's functionality to AI assistants in a structured way.

## Features

This MCP server provides the following capabilities:

### Printify API Integration

- **Authentication**: Initialize the Printify API client with your API key
- **Shops**: List and manage Printify shops
- **Products**: Create, read, update, delete, and publish products
- **Catalog**: Browse blueprints, print providers, and variants
- **Images**: Upload images to use in product designs

### AI Image Generation

- **Replicate Integration**: Generate images using Replicate's Flux 1.1 Pro model
- **Combined Workflow**: Generate images with AI and upload them directly to Printify in one step

### Documentation

- **In-Tool Documentation**: Comprehensive documentation for all aspects of product creation
- **Workflow Guidance**: Step-by-step guides for creating products

### Prompts

- **Generate Product Description**: Generate compelling product descriptions based on product details

## Prerequisites

- Node.js (v18 or higher)
- npm (v7 or higher)
- Printify API key
- Replicate API token (for AI image generation)
- ImgBB API key (required if using the Flux 1.1 Pro Ultra model)

## Installation

```bash
# Clone the repository
git clone https://github.com/tsavo/printify-mcp.git
cd printify-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

You have two options for configuring the environment variables needed by the server:

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

1. Create a `.env` file in the root directory of the project with the following variables:

```
# Required for all functionality
PRINTIFY_API_KEY=your_printify_api_key

# Required if using the Flux 1.1 Pro Ultra model for image generation
# The Ultra model generates high-resolution images that are too large for direct base64 upload
IMGBB_API_KEY=your_imgbb_api_key

# Optional: If not provided, the first shop in your account will be used
PRINTIFY_SHOP_ID=your_shop_id

# Optional: Only needed if you want to use image generation features
REPLICATE_API_TOKEN=your_replicate_api_token
```

You can use the `.env.example` file as a template by copying it:

```bash
cp .env.example .env
# Then edit the .env file with your actual API keys
```

### Option 2: Using System Environment Variables

Alternatively, you can set these variables directly in your system environment:

**Windows (Command Prompt):**
```cmd
:: Required
set PRINTIFY_API_KEY=your_printify_api_key

:: Optional
set PRINTIFY_SHOP_ID=your_shop_id

:: Optional - only for image generation
set REPLICATE_API_TOKEN=your_replicate_api_token
```

**Windows (PowerShell):**
```powershell
# Required
$env:PRINTIFY_API_KEY = "your_printify_api_key"

# Optional
$env:PRINTIFY_SHOP_ID = "your_shop_id"

# Optional - only for image generation
$env:REPLICATE_API_TOKEN = "your_replicate_api_token"
```

**macOS/Linux:**
```bash
# Required
export PRINTIFY_API_KEY=your_printify_api_key

# Optional
export PRINTIFY_SHOP_ID=your_shop_id

# Optional - only for image generation
export REPLICATE_API_TOKEN=your_replicate_api_token
```

The server will check for these environment variables at startup, regardless of whether they're set in a `.env` file or in the system environment.

### Getting a Printify API Key

1. Log in to your Printify account
2. Go to Settings > API
3. Click "Create New API Key"
4. Copy the API key and add it to your `.env` file

### Getting a Replicate API Token

1. Create an account on [Replicate](https://replicate.com/)
2. Go to your account settings
3. Generate an API token
4. Copy the token and add it to your `.env` file

## Usage

### Starting the Server

```bash
npm start
```

This will start the MCP server using the stdio transport, which allows it to communicate with MCP clients like Claude Desktop. The server will automatically initialize the Printify API client using the API key from the environment variable.

### Development Mode

```bash
npm run dev
```

This will start the server in development mode with automatic reloading when files change.

## Using with Claude Desktop

There are three ways to use this MCP server with Claude Desktop:

### Option 1: Install from npm (Recommended)

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

2. Configure your environment variables using either a `.env` file in your current directory or system environment variables as described in the [Configuration](#configuration) section.

3. Configure Claude Desktop:
   - Open Claude Desktop
   - Go to Settings > MCP Servers
   - Click "Add Server"
   - Enter a name for the server (e.g., "Printify MCP")
   - Select "Command" as the transport type
   - Enter `printify-mcp` as the command
   - No arguments are needed
   - Click "Add Server"

4. Test the connection by asking Claude to check the Printify status:
   ```
   Can you check the status of my Printify connection?
   ```

   The `printify-mcp` command runs the same code as the original index.ts file, but packaged as an executable that can be run directly from the command line.

### Option 2: Use with npx

If you don't want to install the package globally, you can use npx:

1. Configure your environment variables as described in the [Configuration](#configuration) section.

2. Configure Claude Desktop:
   - Open Claude Desktop
   - Go to Settings > MCP Servers
   - Click "Add Server"
   - Enter a name for the server (e.g., "Printify MCP")
   - Select "Command" as the transport type
   - Enter `npx` as the command
   - Enter `@tsavo/printify-mcp` as the arguments
   - Click "Add Server"

### Option 3: Use Docker (Recommended for Isolation)

If you prefer to run the server in a Docker container, you have two options:

#### Option 3A: Use the Docker Image Directly from Docker Hub

1. Make sure you have Docker installed on your system

2. Create a directory for your Printify MCP files:
   ```bash
   mkdir printify-mcp
   cd printify-mcp
   ```

3. Create a `.env` file with your API keys:
   ```
   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 (required for Flux 1.1 Pro Ultra model)
   ```

4. Create a temp directory for temporary files:
   ```bash
   mkdir temp
   ```

5. Run the Docker container (two options):

   **Option A: Using environment variables directly (Recommended)**
   ```bash
   # For 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

   # For 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
   ```

   **Note:** If you want to use the image generation features (generate-and-upload-image tool), add the Replicate API token:
   ```bash
   -e REPLICATE_API_TOKEN=your_replicate_api_token \
   ```

   **Important:** If you want to use the Flux 1.1 Pro Ultra model for image generation, you MUST also add the ImgBB API key:
   ```bash
   -e IMGBB_API_KEY=your_imgbb_api_key \
   ```

   **Option B: Using a .env file**
   ```bash
   # For Linux/macOS:
   docker run -it --name printify-mcp \
     -v $(pwd)/.env:/app/.env:ro \
     -v $(pwd)/temp:/app/temp \
     tsavo/printify-mcp:latest

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

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

6. Configure Claude Desktop:
   - Open Claude Desktop
   - Go to Settings > MCP Servers
   - Click "Add Server"
   - Enter a name for the server (e.g., "Printify MCP Docker")
   - Select "Command" as the transport type
   - Enter `docker` as the command
   - Enter `exec -i printify-mcp node dist/index.js` as the arguments
   - Click "Add Server"

#### Option 3B: Build and Run with Docker Compose

1. Make sure you have Docker and Docker Compose installed on your system

2. Clone this repository to your local machine:
   ```bash
   git clone https://github.com/tsavo/printify-mcp.git
   cd printify-mcp
   ```

3. Configure environment variables (two options):

   **Option A: Edit docker-compose.yml directly (Recommended)**
   Open docker-compose.yml and uncomment/edit the environment variables:
   ```yaml
   environment:
     - NODE_ENV=production
     # Option 1: Set environment variables directly (recommended)
     - PRINTIFY_API_KEY=your_printify_api_key
     - PRINTIFY_SHOP_ID=your_shop_id_optional
     # Optional: Only needed if you want to use image generation features
     - REPLICATE_API_TOKEN=your_replicate_api_token
     # Required if using the Flux 1.1 Pro Ultra model for image generation
     - IMGBB_API_KEY=your_imgbb_api_key
   ```

   **Option B: Create a `.env` file**
   ```
   PRINTIFY_API_KEY=your_printify_api_key
   PRINTIFY_SHOP_ID=your_shop_id (optional)
   # Optional: Only needed if you want to use image generation features
   REPLICATE_API_TOKEN=your_replicate_api_token
   # Required if using the Flux 1.1 Pro Ultra model for image generation
   IMGBB_API_KEY=your_imgbb_api_key
   ```
   Then uncomment the .env volume mount in docker-compose.yml:
   ```yaml
   volumes:
     # Option 2: Mount a .env file for environment variables
     - ./.env:/app/.env:ro
   ```

4. Build and start the Docker container:
   ```bash
   docker-compose up -d
   ```

5. Configure Claude Desktop:
   - Open Claude Desktop
   - Go to Settings > MCP Servers
   - Click "Add Server"
   - Enter a name for the server (e.g., "Printify MCP Docker")
   - Select "Command" as the transport type
   - Enter `docker` as the command
   - Enter `exec -i printify-mcp node dist/index.js` as the arguments
   - Click "Add Server"

6. Test the connection by asking Claude to check the Printify status:
   ```
   Can you check the status of my Printify connection?
   ```

### Option 4: Clone and Set Up the Repository

If you prefer to work with the source code directly without Docker:

1. Clone this repository to your local machine:
   ```bash
   git clone https://github.com/tsavo/printify-mcp.git
   cd printify-mcp
   ```

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

3. Configure your environment variables using either a `.env` file or system environment variables as described in the [Configuration](#configuration) section.

4. Get the full absolute path to the compiled JavaScript file:

   **Windows:**
   ```cmd
   cd dist
   echo %CD%\index.js
   ```

   **macOS/Linux:**
   ```bash
   realpath dist/index.js
   ```

5. Configure Claude Desktop:
   - Open Claude Desktop
   - Go to Settings > MCP Servers
   - Click "Add Server"
   - Enter a name for the server (e.g., "Printify MCP")
   - Select "Command" as the transport type
   - Enter the path to Node.js as the command (e.g., `node`)
   - Enter the **full absolute path** to the built server as the arguments
   - Click "Add Server"

6. Start the server:
   ```bash
   npm start
   ```

   Keep this terminal window open while you're using Claude Desktop.

### Testing the Connection

In a conversation with Claude, you can test if the server is working by asking Claude to check the Printify status:

```
Can you check the status of my Printify connection?
```

Claude should use the `get-printify-status` tool to check the connection status. You can also ask Claude to list your Printify shops using the `list-shops` tool.

If you encounter any issues:

1. Check the console output where you started the server for error messages
2. Verify that your environment variables are set correctly
3. Make sure the server is still running
4. Confirm that the path to the server in Claude Desktop is correct

## Available Tools

### Shop Management

#### `get-printify-status`

Get the current status of the Printify API client, including connection status and current shop.

#### `list-shops`

List all available shops in your Printify account. The currently selected shop is marked with an arrow (→).

#### `switch-shop`

Switch to a different shop for subsequent API calls.

Parameters:
- `shopId` (string): The ID of the shop to switch to

### Product Tools

#### `list-products`

List products in your Printify shop.

Parameters:
- `page` (number, optional): Page number (default: 1)
- `limit` (number, optional): Number of products per page (default: 10)

#### `get-product`

Get details of a specific product.

Parameters:
- `productId` (string): Product ID

#### `create-product`

Create a new product in your Printify shop.

Parameters:
- `title` (string): Product title
- `description` (string): Product description
- `blueprintId` (number): Blueprint ID
- `printProviderId` (number): Print provider ID
- `variants` (array): Product variants
- `printAreas` (object, optional): Print areas for the product

#### `update-product`

Update an existing product in your Printify shop.

Parameters:
- `productId` (string): Product ID
- `title` (string, optional): Product title
- `description` (string, optional): Product description
- `variants` (array, optional): Product variants
- `printAreas` (object, optional): Print areas for the product

#### `delete-product`

Delete a product from your Printify shop.

Parameters:
- `productId` (string): Product ID

#### `publish-product`

Publish a product to your connected sales channel.

Parameters:
- `productId` (string): Product ID
- `publishDetails` (obje

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TSavo](https://github.com/TSavo)
- **Source:** [TSavo/printify-mcp](https://github.com/TSavo/printify-mcp)
- **License:** ISC

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tsavo-printify-mcp
- Seller: https://agentstack.voostack.com/s/tsavo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.