Printify MCP Server

Printify MCP 服务

一个用于将 AI 助手与 Printify 按需印刷平台集成的模型上下文协议（MCP）服务。

目录

• 概述
• 功能
• 前提条件
• 安装
• 配置
• 使用方法
  • 启动服务
  • 与 Claude Desktop 搭配使用
  • 使用 Docker
    • Docker Hub 镜像
    • Docker Compose
  • 开发模式
• 可用工具
  • 商店管理
  • 产品管理
  • 蓝图和变体管理
  • 图像管理
  • 文档
  • 提示词
• 工作流示例
  • 使用 AI 生成的设计创建 T 恤
  • 管理现有产品
• 架构
  • 主要组件
  • Docker 架构
  • 发布 Docker 镜像
  • 不使用 Node.js 运行 Docker 镜像
  • 文件结构
• API 文档
• 故障排除
  • 常见问题
  • Docker 特定问题
  • 调试
• 贡献
• 许可证

概述

Printify MCP 服务是 AI 助手（如 Claude）与 Printify 按需印刷平台之间的桥梁。它允许 AI 助手创建和管理按需印刷产品、使用 AI 生成设计，并通过模型上下文协议（MCP）处理产品管理的各个方面。

MCP 是由 Anthropic 开发的一项开放标准，用于规范应用程序向大语言模型（LLM）提供上下文的方式。本服务实现了 MCP 规范，以结构化的方式向 AI 助手开放 Printify 的功能。

功能

此 MCP 服务提供以下功能：

Printify API 集成

• 身份验证：使用 API 密钥初始化 Printify API 客户端
• 商店：列出和管理 Printify 商店
• 产品：创建、读取、更新、删除和发布产品
• 目录：浏览蓝图、印刷服务商和变体
• 图像：上传用于产品设计的图像

AI 图像生成

• Replicate 集成：使用 Replicate 的 Flux 1.1 Pro 模型生成图像
• 组合工作流：使用 AI 生成图像，并一步将其直接上传到 Printify

文档

• 工具内文档：提供有关产品创建各个方面的全面文档
• 工作流指南：提供创建产品的分步指南

提示词

• 生成产品描述：根据产品详情生成吸引人的产品描述

前提条件

• Node.js（v18 或更高版本）
• npm（v7 或更高版本）
• Printify API 密钥
• Replicate API 令牌（用于 AI 图像生成）
• ImgBB API 密钥（使用 Flux 1.1 Pro Ultra 模型时必需）

安装

# 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

配置

你可以通过以下两种方式配置服务所需的环境变量：

选项 1：使用 .env 文件（推荐）

1. 在项目根目录中创建 .env 文件，并添加以下变量：

# 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

你可以复制 .env.example 文件作为模板：

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

选项 2：使用系统环境变量

或者，你可以直接在系统环境中设置这些变量：

Windows（命令提示符）：

:: 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）：

# 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：

# 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

无论这些环境变量是在 .env 文件中还是在系统环境中设置的，服务都会在启动时检查它们。

获取 Printify API 密钥

1. 登录你的 Printify 帐户
2. 转到 Settings > API
3. 点击“Create New API Key”
4. 复制 API 密钥并将其添加到 .env 文件中

获取 Replicate API 令牌

1. 在 Replicate 上创建帐户
2. 转到帐户设置
3. 生成 API 令牌
4. 复制令牌并将其添加到 .env 文件中

使用方法

启动服务

npm start

这会通过 stdio 传输启动 MCP 服务，使其能够与 Claude Desktop 等 MCP 客户端通信。服务会自动使用环境变量中的 API 密钥初始化 Printify API 客户端。

开发模式

npm run dev

这会以开发模式启动服务，并在文件更改时自动重新加载。

与 Claude Desktop 搭配使用

有三种方式可以在 Claude Desktop 中使用此 MCP 服务：

选项 1：从 npm 安装（推荐）

1. 全局安装软件包：

   npm install -g @tsavo/printify-mcp
   

2. 按照配置部分中的说明，使用当前目录中的 .env 文件或系统环境变量配置环境变量。

3. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 转到 Settings > MCP Servers
   • 点击“Add Server”
   • 输入服务名称（例如“Printify MCP”）
   • 选择“Command”作为传输类型
   • 输入 printify-mcp 作为命令
   • 无需提供参数
   • 点击“Add Server”

4. 让 Claude 检查 Printify 状态，以测试连接：

   Can you check the status of my Printify connection?
   

   printify-mcp 命令运行的代码与原始 index.ts 文件相同，但会打包为可直接从命令行运行的可执行文件。

选项 2：使用 npx

如果你不想全局安装软件包，可以使用 npx：

1. 按照配置部分中的说明配置环境变量。

2. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 转到 Settings > MCP Servers
   • 点击“Add Server”
   • 输入服务名称（例如“Printify MCP”）
   • 选择“Command”作为传输类型
   • 输入 npx 作为命令
   • 输入 @tsavo/printify-mcp 作为参数
   • 点击“Add Server”

选项 3：使用 Docker（推荐用于隔离）

如果你更倾向于在 Docker 容器中运行服务，有两种选择：

选项 3A：直接使用 Docker Hub 中的 Docker 镜像

1. 确保系统已安装 Docker

2. 为 Printify MCP 文件创建目录：

   mkdir printify-mcp
   cd printify-mcp
   

3. 创建包含 API 密钥的 .env 文件：

   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. 创建用于存放临时文件的目录：

   mkdir temp
   

5. 运行 Docker 容器（两种方式）：

   选项 A：直接使用环境变量（推荐）

   # 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
   

   **注意：**如果你想使用图像生成功能（generate-and-upload-image 工具），请添加 Replicate API 令牌：

   -e REPLICATE_API_TOKEN=your_replicate_api_token \
   

   **重要：**如果你想使用 Flux 1.1 Pro Ultra 模型生成图像，还必须添加 ImgBB API 密钥：

   -e IMGBB_API_KEY=your_imgbb_api_key \
   

   选项 B：使用 .env 文件

   # 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. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 转到 Settings > MCP Servers
   • 点击“Add Server”
   • 输入服务名称（例如“Printify MCP Docker”）
   • 选择“Command”作为传输类型
   • 输入 docker 作为命令
   • 输入 exec -i printify-mcp node dist/index.js 作为参数
   • 点击“Add Server”

选项 3B：使用 Docker Compose 构建并运行

1. 确保系统已安装 Docker 和 Docker Compose

2. 将此仓库克隆到本地计算机：

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

3. 配置环境变量（两种方式）：

   选项 A：直接编辑 docker-compose.yml（推荐） 打开 docker-compose.yml，取消注释并编辑环境变量：

   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
   

   选项 B：创建 .env 文件

   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
   

   然后取消注释 docker-compose.yml 中的 .env 卷挂载：

   volumes:
     # Option 2: Mount a .env file for environment variables
     - ./.env:/app/.env:ro
   

4. 构建并启动 Docker 容器：

   docker-compose up -d
   

5. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 转到 Settings > MCP Servers
   • 点击 "Add Server"
   • 输入服务名称（例如 "Printify MCP Docker"）
   • 选择 "Command" 作为传输类型
   • 输入 docker 作为命令
   • 输入 exec -i printify-mcp node dist/index.js 作为参数
   • 点击 "Add Server"

6. 通过让 Claude 检查 Printify 状态来测试连接：

   Can you check the status of my Printify connection?
   

选项 4：克隆并设置仓库

如果你希望直接使用源代码而不使用 Docker：

1. 将此仓库克隆到本地计算机：

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

2. 安装依赖并构建项目：

   npm install
   npm run build
   

3. 按照配置部分所述，使用 .env 文件或系统环境变量配置环境变量。

4. 获取已编译 JavaScript 文件的完整绝对路径：

   Windows：

   cd dist
   echo %CD%\index.js
   

   macOS/Linux：

   realpath dist/index.js
   

5. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 转到 Settings > MCP Servers
   • 点击 "Add Server"
   • 输入服务名称（例如 "Printify MCP"）
   • 选择 "Command" 作为传输类型
   • 输入 Node.js 的路径作为命令（例如 node）
   • 输入构建完成的服务的完整绝对路径作为参数
   • 点击 "Add Server"

6. 启动服务：

   npm start
   

   使用 Claude Desktop 时，请保持此终端窗口处于打开状态。

测试连接

在与 Claude 的对话中，你可以让 Claude 检查 Printify 状态，以测试服务是否正常运行：

Can you check the status of my Printify connection?

Claude 应使用 get-printify-status 工具检查连接状态。你也可以让 Claude 使用 list-shops 工具列出你的 Printify 商店。

如果遇到问题：

1. 查看启动服务的控制台输出，检查是否有错误消息
2. 确认环境变量设置正确
3. 确保服务仍在运行
4. 确认 Claude Desktop 中的服务路径正确

可用工具

商店管理

get-printify-status

获取 Printify API 客户端的当前状态，包括连接状态和当前商店。

list-shops

列出 Printify 账户中所有可用的商店。当前选中的商店会用箭头（→）标记。

switch-shop

切换到其他商店，以供后续 API 调用使用。

参数：

• shopId（字符串）：要切换到的商店 ID

产品工具

list-products

列出 Printify 商店中的产品。

参数：

• page（数字，可选）：页码（默认值：1）
• limit（数字，可选）：每页显示的产品数量（默认值：10）

get-product

获取特定产品的详细信息。

参数：

• productId（字符串）：产品 ID

create-product

在 Printify 商店中创建新产品。

参数：

• title（字符串）：产品标题
• description（字符串）：产品描述
• blueprintId（数字）：蓝图 ID
• printProviderId（数字）：印刷服务提供商 ID
• variants（数组）：产品变体
• printAreas（对象，可选）：产品的印刷区域

update-product

更新 Printify 商店中的现有产品。

参数：

• productId（字符串）：产品 ID
• title（字符串，可选）：产品标题
• description（字符串，可选）：产品描述
• variants（数组，可选）：产品变体
• printAreas（对象，可选）：产品的印刷区域

delete-product

从 Printify 商店中删除产品。

参数：

• productId（字符串）：产品 ID

publish-product

将产品发布到已连接的销售渠道。

参数：

• productId（字符串）：产品 ID
• publishDetails（对象，可选）：发布详情

目录工具

get-blueprints

从 Printify 目录中获取可用蓝图列表。

参数：

• page（数字，可选）：页码（默认值：1）
• limit（数字，可选）：每页蓝图数量（默认值：10）

get-blueprint

获取特定蓝图的详细信息。

参数：

• blueprintId（字符串）：蓝图 ID

get-print-providers

获取特定蓝图的印刷服务商列表。

参数：

• blueprintId（字符串）：蓝图 ID

get-variants

获取特定蓝图和印刷服务商的变体列表。

参数：

• blueprintId（字符串）：蓝图 ID
• printProviderId（字符串）：印刷服务商 ID

图像工具

generate-and-upload-image

使用 Replicate 的 Flux 模型生成图像，通过 Sharp 处理后，一次性上传到 Printify。此工具将 AI 图像生成与 Printify 集成相结合，实现无缝工作流。

该工具分四步执行：

1. 根据你的文本提示词，使用 Replicate 的 Flux 模型生成图像
2. 使用 Sharp 处理图像，确保其为有效图像且格式符合 Printify 的要求
3. 将处理后的图像上传到你的 Printify 账户
4. 清理临时文件，避免磁盘空间问题

参数：

• prompt（字符串）：用于生成图像的文本提示词
• fileName（字符串）：上传图像的文件名
• model（字符串，可选）：覆盖默认模型（例如，"black-forest-labs/flux-1.1-pro-ultra"）
• width（数字，可选）：图像宽度，单位为像素（默认值：1024）
• height（数字，可选）：图像高度，单位为像素（默认值：1024）
• aspectRatio（字符串，可选）：宽高比（例如，'16:9'、'4:3'、'1:1'）。如果提供此参数，则覆盖宽度和高度
• outputFormat（字符串，可选）：输出格式（"jpeg"、"png"、"webp"）（默认值："png"）
• numInferenceSteps（数字，可选）：推理步数（默认值：25）
• guidanceScale（数字，可选）：引导系数（默认值：7.5）
• negativePrompt（字符串，可选）：负面提示词（默认值："low quality, bad quality, sketches"）
• seed（数字，可选）：用于可复现生成的随机种子
• raw（布尔值，可选）：生成处理较少、外观更自然的图像（Flux 1.1 Pro Ultra 的默认值：true）

**注意：**此工具要求设置 REPLICATE_API_TOKEN 环境变量，并填入有效的 Replicate API 令牌。你可以从 replicate.com 获取令牌。

**重要：**如果要使用 Flux 1.1 Pro Ultra 模型，还必须设置 IMGBB_API_KEY 环境变量。Ultra 模型生成的高分辨率图像过大，无法直接以 base64 格式上传到 Printify。你可以从 api.imgbb.com 免费获取 API 密钥。

generate-image

使用 Replicate 的 Flux 模型生成图像，并将其保存到本地文件，不上传到 Printify。如果你想将图像用于其他用途，或者希望在上传到 Printify 之前先查看并可能编辑图像，此工具会很有用。

参数：

• prompt（字符串）：用于生成图像的文本提示词
• outputPath（字符串）：生成图像的保存位置完整路径
• model（字符串，可选）：覆盖默认模型（例如，"black-forest-labs/flux-1.1-pro-ultra"）
• width（数字，可选）：图像宽度，单位为像素（默认值：1024）
• height（数字，可选）：图像高度，单位为像素（默认值：1024）
• aspectRatio（字符串，可选）：宽高比（例如，'16:9'、'4:3'、'1:1'）。如果提供此参数，则会覆盖宽度和高度
• outputFormat（字符串，可选）：输出格式（"jpeg"、"png"、"webp"）（默认值："png"）
• numInferenceSteps（数字，可选）：推理步数（默认值：25）
• guidanceScale（数字，可选）：引导系数（默认值：7.5）
• negativePrompt（字符串，可选）：负面提示词（默认值："low quality, bad quality, sketches"）
• seed（数字，可选）：用于可复现生成的随机种子
• raw（布尔值，可选）：生成处理程度较低、更自然的图像（仅限 Flux 1.1 Pro Ultra）

**注意：**此工具要求设置 REPLICATE_API_TOKEN 环境变量，并提供有效的 Replicate API 令牌。你可以从 replicate.com 获取令牌。

与 generate-and-upload-image 工具不同，此工具无需 ImgBB API 密钥，因为它会直接将图像保存到本地文件。

upload-image

将图像上传到你的 Printify 账户。支持三种输入类型：

1. URL（http:// 或 https://）——直接上传到 Printify
2. 本地文件路径（例如，c:\path\to\image.png）——自动使用 Sharp 转换以确保兼容性，然后上传到 Printify
3. Base64 编码的图像字符串——直接上传到 Printify

文件格式说明：

• 支持的格式：PNG、JPEG 和 SVG
• JPEG/PNG 文件的推荐分辨率为 300 DPI
• 对于较大的产品（打底裤、毯子、挂毯），120-150 DPI 也可以接受
• 如果图像文件超出大小限制，可能无法兼容 Printify 的 API
• 对于大于 5MB 的文件，建议使用 URL 上传，而非 Base64 编码

参数：

• fileName（字符串）：文件名
• url（字符串）：要上传的图像 URL、本地文件路径或 Base64 编码的图像数据

提示词

generate-product-description

生成引人注目的产品描述。

参数：

• productName（字符串）：产品名称
• category（字符串）：产品类别
• targetAudience（字符串，可选）：产品的目标受众
• keyFeatures（字符串，可选）：以逗号分隔的产品主要特性列表

设置 API 密钥

Printify API 密钥

要使用此 MCP 服务的 Printify 功能，你需要 Printify API 密钥。获取并设置密钥的方法如下：

1. 登录你的 Printify 账户：printify.com

2. 前往 My Profile > Connections

3. 在 Connections 部分，你可以生成个人访问令牌

4. 请妥善保管 API 密钥，因为生成后仅会立即显示一次

5. 在项目根目录中创建 .env 文件，并添加以下内容：

   PRINTIFY_API_KEY=your_api_key_here
   # Optional: Set a default shop ID
   # PRINTIFY_SHOP_ID=your_shop_id_here
   
   # For image generation with Replicate
   REPLICATE_API_TOKEN=your_replicate_token_here
   
   # Required if using the Flux 1.1 Pro Ultra model for image generation
   IMGBB_API_KEY=your_imgbb_api_key_here
   

   服务器会自动使用环境变量中的 API 密钥初始化 Printify API 客户端。如果你未指定商店 ID，服务器将默认使用你账户中的第一家商店。

   你也可以直接设置环境变量：

   # On Windows
   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
   
   # On macOS/Linux
   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 令牌

要使用此 MCP 服务的图像生成功能，你需要 Replicate API 令牌。获取方法如下：

1. 在 replicate.com 创建账户或登录
2. 前往账户设置
3. 生成 API 令牌
4. 按照上文所示，将令牌添加到 .env 文件中

ImgBB API 密钥

如果要使用 Flux 1.1 Pro Ultra 模型生成图像，必须拥有 ImgBB API 密钥。Ultra 模型生成的高分辨率图像太大，无法直接以 base64 格式上传到 Printify，因此我们使用 ImgBB 作为中转。获取 API 密钥的方法如下：

1. 在 imgbb.com 创建账户或登录
2. 前往 api.imgbb.com 获取 API 密钥
3. 按照上文所示，将密钥添加到 .env 文件中

工作流示例

使用 AI 生成的设计制作 T 恤

以下是制作正面和背面均带有设计的 T 恤的完整示例：

// Step 1: Get blueprints and choose one
get-blueprints_printify()
// Selected blueprint ID 12 (Unisex Jersey Short Sleeve Tee)

// Step 2: Get print providers for this blueprint
get-print-providers_printify({ blueprintId: "12" })
// Selected print provider ID 29 (Monster Digital)

// Step 3: Get variants for this blueprint and print provider
get-variants_printify({ blueprintId: "12", printProviderId: "29" })
// Selected variant IDs 18100 (Black / S), 18101 (Black / M), 18102 (Black / L)

// Step 4: Generate and upload front image
const frontImage = await generate-and-upload-image_printify({
  prompt: "A futuristic cityscape with neon lights and tall skyscrapers, horizon city logo design",
  fileName: "horizon-city-front"
})
// Got image ID: 68032b22ae74bf725ed406ec

// Step 4b: Generate and upload back image
const backImage = 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"
})
// Got image ID: 68032b377e36fbdd32791027

// Step 5: Create the product
create-product_printify({
  title: "Horizon City Skyline T-Shirt",
  description: "Step into the future with our Horizon City Skyline T-Shirt. This premium unisex tee features a stunning futuristic cityscape with neon lights and towering skyscrapers on the front, and a sleek minimalist Horizon City logo on the back.",
  blueprintId: 12,
  printProviderId: 29,
  variants: [
    { variantId: 18100, price: 2499 },
    { variantId: 18101, price: 2499 },
    { variantId: 18102, price: 2499 }
  ],
  printAreas: {
    "front": { position: "front", imageId: "68032b22ae74bf725ed406ec" },
    "back": { position: "back", imageId: "68032b377e36fbdd32791027" }
  }
})
// Product created with ID: 68032b43a24efbac6502b6f7

管理现有商品

// List products
list-products_printify()

// Get details of a specific product
get-product_printify({ productId: "68032b43a24efbac6502b6f7" })

// Update a product
update-product_printify({
  productId: "68032b43a24efbac6502b6f7",
  title: "Updated Horizon City Skyline T-Shirt",
  description: "Updated description...",
  variants: [
    { variantId: 18100, price: 2999 },
    { variantId: 18101, price: 2999 },
    { variantId: 18102, price: 2999 }
  ]
})

// Publish a product to external sales channels
publish-product_printify({
  productId: "68032b43a24efbac6502b6f7",
  publishDetails: {
    title: true,
    description: true,
    images: true,
    variants: true,
    tags: true
  }
})

// Delete a product
delete-product_printify({ productId: "68032b43a24efbac6502b6f7" })

架构

主要组件

Printify MCP 服务由三个主要组件构成：

1. MCP 服务端（src/index.ts）：配置 MCP 服务端，并提供用于与 Printify API 交互的各种工具。
2. Printify API 客户端（src/printify-api.ts）：使用官方 SDK 处理与 Printify API 的通信。
3. Replicate 客户端（src/replicate-client.ts）：集成 Replicate API，为商品设计生成图像。

Docker 架构

Docker 配置由以下组件构成：

1. Dockerfile：定义如何构建 Docker 镜像

   • 使用 Node.js 22 Alpine 作为基础镜像，以缩小镜像体积
   • 安装依赖并构建 TypeScript 代码
   • 设置环境并运行服务

2. docker-compose.yml：定义服务配置

   • 设置环境变量
   • 挂载用于 .env 文件和临时目录的卷
   • 为 stdio 传输配置 stdin 和 tty
   • 配置重启策略

3. 卷：

   • .env：作为只读卷挂载，用于存放环境变量
   • temp：作为卷挂载，用于存放临时文件（例如生成的图像）

发布 Docker 镜像

你可以将 Docker 镜像发布到 Docker Hub 或其他容器镜像仓库，以便他人使用，而无需安装 Node.js 或克隆代码仓库。

1. 构建 Docker 镜像：

   docker build -t tsavo/printify-mcp:latest .
   

2. 登录 Docker Hub：

   docker login
   

3. 将镜像推送到 Docker Hub：

   docker push tsavo/printify-mcp:latest
   

不安装 Node.js 使用 Docker 镜像

用户可以直接使用 Docker 镜像运行 Printify MCP 服务，无需安装 Node.js：

1. 安装 Docker：用户需要在自己的系统上安装 Docker

2. 创建临时目录，用于存放临时文件：

   mkdir -p temp
   

3. 运行 Docker 容器（两种方式）：

   方式 A：直接使用环境变量（推荐）

   docker run -it --name printify-mcp \
     -e PRINTIFY_API_KEY=their_printify_api_key \
     -e PRINTIFY_SHOP_ID=their_shop_id_optional \
     -v $(pwd)/temp:/app/temp \
     tsavo/printify-mcp:latest
   

   **注意：**如果要使用图像生成功能（generate-and-upload-image 工具），请添加 Replicate API 令牌：

   -e REPLICATE_API_TOKEN=their_replicate_api_token \
   

   **重要：**如果要使用 Flux 1.1 Pro Ultra 模型生成图像，还必须添加 ImgBB API 密钥：

   -e IMGBB_API_KEY=their_imgbb_api_key \
   

   方式 B：使用 .env 文件 首先，创建包含 API 密钥的 .env 文件：

   PRINTIFY_API_KEY=their_printify_api_key
   PRINTIFY_SHOP_ID=their_shop_id (optional)
   # Optional: Only needed if they want to use image generation features
   REPLICATE_API_TOKEN=their_replicate_api_token
   # Required if using the Flux 1.1 Pro Ultra model for image generation
   IMGBB_API_KEY=their_imgbb_api_key
   

   然后运行容器：

   docker run -it --name printify-mcp \
     -v $(pwd)/.env:/app/.env:ro \
     -v $(pwd)/temp:/app/temp \
     tsavo/printify-mcp:latest
   

4. 配置 Claude Desktop：

   • 打开 Claude Desktop
   • 前往 Settings > MCP Servers
   • 点击 "Add Server"
   • 输入服务名称（例如 "Printify MCP Docker"）
   • 选择 "Command" 作为传输类型
   • 输入 docker 作为命令
   • 输入 exec -i printify-mcp node dist/index.js 作为参数
   • 点击 "Add Server"

通过这种方式，用户无需安装 Node.js 或任何其他依赖项即可运行 Printify MCP 服务——只需要 Docker。

文件结构

printify-mcp/
├── dist/                  # Compiled JavaScript files
├── docs/                  # Documentation
│   ├── index.ts.md        # Documentation for index.ts
│   ├── printify-api.ts.md # Documentation for printify-api.ts
│   └── replicate-client.ts.md # Documentation for replicate-client.ts
├── node_modules/          # Node.js dependencies
├── src/                   # Source code
│   ├── index.ts           # Main MCP server
│   ├── printify-api.ts    # Printify API client
│   └── replicate-client.ts # Replicate API client
├── temp/                  # Temporary directory for generated images
├── .dockerignore          # Files to exclude from Docker build
├── .env                   # Environment variables (not in repo)
├── .env.example           # Example environment variables
├── .gitignore             # Git ignore file
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile             # Docker build instructions
├── package.json           # Node.js package configuration
├── package-lock.json      # Node.js package lock
├── README.md              # This file
└── tsconfig.json          # TypeScript configuration

API 文档

如需查看代码库的详细文档，请参阅以下文件：

• index.ts 文档
• printify-api.ts 文档
• replicate-client.ts 文档

故障排除

常见问题

Printify API 客户端未初始化

如果看到错误“Printify API 客户端未初始化”，请检查：

1. .env 文件中的 PRINTIFY_API_KEY 环境变量是否设置正确
2. API 密钥是否有效且具有正确的权限

Replicate API 客户端未初始化

如果看到错误“Replicate API 客户端未初始化”，请检查：

1. .env 文件中的 REPLICATE_API_TOKEN 环境变量是否设置正确
2. API 令牌是否有效且具有正确的权限

创建产品时出错

如果创建产品时遇到错误，请检查：

1. blueprint ID 和 print provider ID 是否有效
2. 所选 blueprint 和 print provider 对应的 variant ID 是否有效
3. print areas 中的 image ID 是否有效且可访问
4. 请求中是否包含所有必填字段

上传图片时出错

如果上传图片时遇到错误，请检查：

1. 图片是否为有效格式（PNG、JPEG 等）
2. 图片是否过大（最大大小为 10MB）
3. 如果使用 URL，该 URL 是否可公开访问
4. 如果使用本地文件，该文件是否存在且可读取

Docker 特定问题

如果使用 Docker 配置时遇到问题：

1. 容器无法启动：使用 docker logs printify-mcp 检查 Docker 日志
2. 环境变量不起作用：如果使用 .env 文件，请确保它与 docker-compose.yml 文件位于同一目录，或者位于运行 docker run 命令的目录中。如果使用 -e 直接设置环境变量，请检查变量名称是否有拼写错误
3. 临时目录权限问题：临时目录作为卷挂载，请确保它具有正确的权限
4. Claude 连接问题：使用 docker ps 确认 Docker 容器正在运行，并确保已正确配置 Claude Desktop
5. 找不到镜像：如果直接使用 Docker Hub 镜像，请确保已使用 docker pull tsavo/printify-mcp:latest 拉取该镜像

使用 docker-compose 时，重启 Docker 容器：

docker-compose down
docker-compose up -d

使用 docker run 时，重启 Docker 容器：

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

对于使用 Docker 镜像的 Windows PowerShell 用户：

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

对于使用 Docker 镜像的 Windows 命令提示符用户：

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

调试

服务包含详细日志，可帮助排查问题。请查看控制台输出中的错误消息和调试信息。

对于 Docker 部署，可以使用以下命令查看日志：

docker logs printify-mcp

要实时跟踪日志：

docker logs -f printify-mcp

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

ISC