Etsy MCP Server

Etsy MCP 服务

一个用于与 Etsy API 交互的 MCP（Model Context Protocol）服务。此服务负责身份验证、调用 Etsy API 管理商品列表、店铺详情、配送资料和图片上传。

概览

此服务提供一组可通过 Model Context Protocol（MCP）访问的工具，用于与 Etsy V3 API 交互。它管理 OAuth 2.0 身份验证流程（包括 PKCE 令牌刷新），安全地存储令牌，并提供创建商品列表、获取店铺数据、管理配送资料和上传图片等功能。其目标是简化 MCP 兼容客户端与 Etsy API 的交互。

此 MCP 服务主要面向开发和工具集成。请确保遵守 Etsy 的 API 使用条款。

功能

• 🔑 OAuth2 身份验证：处理完整的 Etsy OAuth2 PKCE 流程。
• 🛍️ 商品列表管理：创建和检索 Etsy 商品列表。
• ℹ️ 店铺信息：获取 Etsy 店铺详情。
• 📦 配送资料：列出并创建店铺的配送资料。
• 🖼️ 图片上传：上传图片并将其关联到商品列表。
• 🔧 默认店铺管理：设置和获取默认店铺，以便更轻松地管理多个店铺。
• 🔒 安全令牌存储：安全地持久化 OAuth 令牌。

安装

前置条件

• Node.js（建议使用 18.0.0 或更高版本，详见 package.json 中的 engines）
• npm（通常随 Node.js 一同安装）或 yarn

手动安装

1. 克隆代码库（如果将代码库托管在 GitHub/GitLab 等平台，请替换为你的代码库 URL）：

   git clone <your-repository-url>
   cd etsy-mcp
   

   （如果在本地操作，可以跳过克隆步骤，直接 cd 进入项目目录。）

2. 安装依赖：

   npm install
   

   或者，如果使用 yarn：

   yarn install
   

3. 配置环境变量： 将 .env.example 文件复制为名为 .env 的新文件：

   cp .env.example .env
   

   然后打开 .env 并填写 Etsy 应用凭据：

   ETSY_API_KEY=YOUR_ETSY_APP_API_KEY
   ETSY_CLIENT_SECRET=YOUR_ETSY_APP_CLIENT_SECRET
   # Optional: define a specific host and port for the OAuth callback redirect URI
   # ETSY_MCP_HOST=localhost
   # ETSY_MCP_OAUTH_PORT=3003
   # ETSY_MCP_REDIRECT_URI=http://localhost:3003/oauth/callback
   # Optional: define a custom path for token storage and logs
   # ETSY_MCP_TOKEN_PATH=/path/to/your/token_storage_directory
   # ETSY_MCP_LOG_PATH=/path/to/your/logs_directory
   # Optional: Your default shipping profile ID for physical items
   # SHIPPING_PROFILE_ID=YOUR_DEFAULT_SHIPPING_PROFILE_ID
   

   注意：.env 文件中的 REDIRECT_URI（或默认值 http://localhost:3003/oauth/callback）必须与 Etsy 应用配置的某个重定向 URI 匹配。

使用方法

运行服务

• 生产/构建版本：

  npm run build
  npm start
  

• 开发模式（自动重新加载）：

  npm run dev
  

这将启动服务并监听 MCP 命令，通常通过标准输入/输出进行通信。

在 Cursor IDE（或其他 MCP 客户端）中使用

要通过 Cursor IDE 这样的 MCP 客户端使用此 Etsy MCP 服务，通常需要提供 JSON 配置。

在 Cursor 设置中，导航至 MCP 选项卡，点击“+ Add new global MCP server”，然后输入：

{
    "mcpServers": {
        "Etsy MCP": {
            "command": "npm",
            "args": ["run", "dev"],
            "env": {
                "ETSY_API_KEY": "YOUR_ETSY_API_KEY_HERE",
                "ETSY_CLIENT_SECRET": "YOUR_ETSY_CLIENT_SECRET_HERE"
                // Add other ENV VARS from your .env if needed, e.g., REDIRECT_URI
                // "REDIRECT_URI": "http://localhost:3003/oauth/callback"
                // "SHIPPING_PROFILE_ID": "YOUR_DEFAULT_SHIPPING_PROFILE_ID_HERE"
            },
            "cwd": "/Users/name/Desktop/repos/ai gemini apps/etsy_api/etsy-mcp" // IMPORTANT: Update this to the correct absolute path of your project
        }
    }
}

客户端配置要点：

• command 和 args：示例使用 npm run dev 进行开发。在生产环境中，你可以使用 npm start（如果尚未构建，则会先执行 npm run build）。
• env：
  • 如果你不想依赖 npm run dev 脚本从 .env 文件中读取凭据，请将 YOUR_ETSY_API_KEY_HERE 和 YOUR_ETSY_CLIENT_SECRET_HERE 替换为你的实际凭据。通常最好让服务从其 .env 文件中读取凭据。以上示例用于覆盖凭据，或确保凭据已在客户端的执行环境中设置。
• cwd：务必将其更新为你的计算机上 etsy-mcp 项目所在的绝对路径。
• 也可以在此处定义 tools 数组，但服务本身会报告其功能，因此如果客户端能够动态获取这些信息，通常无需在客户端静态配置中设置该数组。

API 参考

该服务提供以下 MCP 工具。参数基于服务中定义的 Zod 模式。

authenticate()

启动与 Etsy 的 OAuth2 身份验证流程。

• 说明：启动身份验证流程。服务将返回一个 URL，你需要在浏览器中打开该 URL，授权访问你的 Etsy 账户。
• 参数：无。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "Please visit this URL to authorize the application: https://www.etsy.com/oauth/connect?response_type=code&client_id=YOUR_API_KEY...\nComplete the process in your browser. You can then use other tools."
    }
  ]
}

set_default_shop()

获取你的 Etsy 店铺，并将找到的第一个店铺设为当前会话的默认店铺。

• 说明：身份验证成功后，使用此工具选择默认店铺。如果你有多个店铺，它会自动使用 Etsy 返回的第一个店铺。除非其他工具显式提供 shop_id，否则将使用此默认店铺。
• 参数：无。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "Default shop set to: YourShopName (ID: 12345678). Other tools will now use this shop unless a specific shop_id is provided."
    }
  ]
}

如果未找到店铺，则返回：

{
  "content": [
    {
      "type": "text",
      "text": "No shops found for your Etsy account."
    }
  ]
}

get_default_shop()

获取当前配置的默认 Etsy 店铺 ID 和名称。

• 说明：使用此工具查看当前设为默认的店铺。
• 参数：无。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "Current default shop: YourShopName (ID: 12345678)"
    }
  ]
}

如果未设置默认店铺，则返回：

{
  "content": [
    {
      "type": "text",
      "text": "No default shop is currently set. Please run the `set_default_shop` tool after authenticating."
    }
  ]
}

get_listings(shop_id?: number)

获取某个店铺的所有在售商品。

• 参数：
  • shop_id（number，可选）：店铺的 ID。如果未提供，则使用默认店铺。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"listing_id\": 123456789,\n      \"user_id\": 98765432,\n      \"shop_id\": 12345678,\n      \"title\": \"Handmade Ceramic Mug\",\n      \"description\": \"A beautiful handmade ceramic mug...\",\n      \"state\": \"active\",\n      \"price\": { \"amount\": 2500, \"divisor\": 100, \"currency_code\": \"USD\" },\n      \"quantity\": 5,\n      /* ... other listing fields ... */\n    }\n  ]\n}"
    }
  ]
}

get_shop_details(shop_id?: number)

获取指定店铺的详细信息。

• 参数：
  • shop_id（number，可选）：店铺的 ID。如果未提供，则使用默认店铺。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"shop_id\": 12345678,\n  \"shop_name\": \"YourShopName\",\n  \"user_id\": 98765432,\n  \"title\": \"Unique Handmade Goods\",\n  \"status\": \"active\",\n  /* ... other shop fields ... */\n}"
    }
  ]
}

create_listing(shop_id?: number, listing_data: object)

创建新的 Etsy 商品。

• 说明：对于实物商品，请确保提供 shipping_profile_id。要添加图片，请先创建商品，然后使用返回的 listing_id 调用 upload_listing_image 工具。
• 参数：
  • shop_id（number，可选）：店铺的 ID。如果未提供，则使用默认店铺。
  • listing_data（object）：
    • title（string）：商品标题。
    • description（string）：商品描述。
    • price（number）：商品价格（例如，25.99）。
    • quantity（number）：可售数量。
    • who_made（string）：例如，'i_did'、'collective'、'someone_else'。
    • when_made（string）：例如，'made_to_order'、'2020_2024'、'1950_1959'。
    • taxonomy_id（number）：商品类别的数字 ID。
    • shipping_profile_id（number，可选）：配送配置文件的数字 ID。如果 type 为 'physical'，则必填。
    • type（枚举：“physical”、“digital”、“download”）：商品类型。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"listing_id\": 123456790,\n  \"user_id\": 98765432,\n  \"shop_id\": 12345678,\n  \"title\": \"New Awesome Product\",\n  /* ... other fields of the newly created listing ... */\n}"
    }
  ]
}

list_shop_shipping_profiles(shop_id?: number)

列出指定店铺的所有配送档案。

• 参数：
  • shop_id (number，可选)：店铺 ID。如果未提供，则使用默认店铺。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"shipping_profile_id\": 7654321,\n      \"title\": \"Standard US Shipping\",\n      \"origin_country_iso\": \"US\",\n      /* ... other shipping profile fields ... */\n    }\n  ]\n}"
    }
  ]
}

create_shop_shipping_profile(shop_id?: number, title: string, origin_country_iso: string, primary_cost: number, secondary_cost: number, min_processing_time: number, max_processing_time: number, destination_country_iso?: string, destination_region?: string)

为店铺创建新的配送档案。

• 参数：
  • shop_id (number，可选)：店铺 ID。如果未提供，则使用默认店铺。
  • title (string)：配送档案的标题（例如，'US Standard'）。
  • origin_country_iso (string，长度为 2)：发货国家/地区的 ISO 代码（例如，'US'）。
  • primary_cost (number，最小值为 0)：仅配送此商品至该目的地的费用。
  • secondary_cost (number，最小值为 0)：与另一件商品一同配送的费用。
  • min_processing_time (integer，最小值为 1)：处理订单所需的最少天数。
  • max_processing_time (integer，最小值为 1)：处理订单所需的最多天数。
  • destination_country_iso (string，长度为 2，可选)：特定目的地国家/地区的 ISO 代码。
  • destination_region (enum："eu"、"non_eu"、"none"，可选)：特定目的地区域。 (注意：必须提供 destination_country_iso 或 destination_region，但不能同时提供两者。)
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"shipping_profile_id\": 7654322,\n  \"title\": \"New Express Profile\",\n  /* ... other fields of the newly created shipping profile ... */\n}"
    }
  ]
}

upload_listing_image(shop_id?: number, listing_id: number, file_name: string, image_name?: string)

从预定义的本地服务端目录上传图片，并将其关联到 Etsy 商品。

• 说明：创建商品后，使用此工具上传图片。图片必须放在服务端的 public/uploads/listing_images 目录中（相对于项目根目录）。
• 参数：
  • shop_id (number，可选)：店铺 ID。未提供时使用默认值。
  • listing_id (integer)：要添加图片的商品 ID。
  • file_name (string)：位于服务端 public/uploads/listing_images 目录中的图片文件名（例如，'my_image.jpg'）。
  • image_name (string，可选)：图片在 Etsy 上使用的文件名。未提供时默认为 file_name。
• 返回：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"listing_image_id\": 987654321,\n  \"listing_id\": 123456790,\n  \"hex_code\": \"f1e2d3\",\n  \"url_75x75\": \"https://.../75x75.jpg\",\n  /* ... other image details ... */\n}"
    }
  ]
}

工作原理

1. 客户端请求：MCP 客户端向此服务发送工具调用请求（例如，在本地运行时通过 stdio 发送）。
2. 身份验证检查：对于需要身份验证的工具，服务会使用 TokenStorage 检查 OAuth 令牌是否有效。
3. OAuth 流程（如有需要）： a. 如果不存在有效令牌，客户端通常会调用 authenticate 工具（或由服务指示调用）。 b. EtsyMCPServer 会调用 OAuthServer，生成 Etsy 授权 URL（使用 PKCE）。 c. 用户在浏览器中打开此 URL 并授权应用程序。 d. Etsy 将用户重定向到 OAuthServer 的回调端点，并附上授权码。 e. OAuthServer 使用 PKCE 代码验证器将授权码兑换为访问令牌和刷新令牌。 f. TokenStorage 会保存令牌（包括 user_id，以及可能存在的默认 shop_id 和 shop_name）。
4. API 调用：EtsyMCPServer 使用持有访问令牌的 EtsyApiClient，向 Etsy V3 API 发起所请求的 API 调用。
5. 令牌刷新：如果访问令牌已过期，EtsyMCPServer 中的 getValidAccessToken() 会尝试使用刷新令牌获取新的访问令牌。
6. 响应：Etsy API 的响应经过处理后，会以标准 MCP 格式返回给 MCP 客户端。

故障排查

• 身份验证错误 / 授权无效：
  • 确保 .env 中的 ETSY_API_KEY、ETSY_CLIENT_SECRET 正确。
  • 确认服务使用的 REDIRECT_URI（默认为 http://localhost:3003/oauth/callback，或在 .env 中设置的值）与 Etsy 应用设置中配置的某个“回调 URL”完全匹配。
  • 令牌过期：尝试从令牌存储路径中删除 tokens.json（请参阅 TokenStorage.ts 或 ETSY_MCP_TOKEN_PATH 环境变量），然后重新进行身份验证。
• OAuth 服务出现 EADDRINUSE：这表示 OAuth 回调服务使用的端口（默认为 3003）已被占用。请停止其他进程，或在 .env 文件中配置其他 ETSY_MCP_OAUTH_PORT，并相应更新 Etsy 应用的重定向 URI。
• 找不到要上传的图像文件：确保提供给 upload_listing_image 的 file_name 存在于相对于项目根目录的 public/uploads/listing_images/ 目录中。
• 日志文件：检查 logs 目录（或 ETSY_MCP_LOG_PATH）中生成的日志文件，以查看详细错误信息。每次运行都会创建一个带时间戳的日志文件。

许可证

MIT 许可证（如果选择使用此许可证，请创建包含 MIT 许可证文本的 LICENSE 文件，或指定其他许可证。）

赞助商

• Resold
• Vinta
• House Illustrator
• GitClip