使用说明

Etsy MCP服务器

用于与Etsy API交互的MCP（模型上下文协议）服务器。该服务处理身份验证、对Etsy的API调用，以管理列表、商店详细信息、装运配置文件和图像上载。

概述

该服务提供了一组可通过模型上下文协议（MCP）访问的工具，以与Etsy V3 API交互。它管理OAuth 2.0身份验证流（包括PKCE令牌刷新），安全地存储令牌，并公开创建列表、获取店铺数据、管理配送配置文件和上传图像等功能。目标是简化与MCP兼容客户端的Etsy API交互。

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

特性

🔑 OAuth2身份验证：使用PKCE处理完整的Etsy OAuth2流。
🛍️ 上市管理：创建和检索Etsy列表。
ℹ️ 店铺信息：获取Etsy商店的详细信息。
📦 运输概况：为您的店铺列出并创建配送配置文件。
🖼️ 图片上传：上传图片并将其与您的列表相关联。
🔧 默认店铺管理：设置并获取默认店铺，以便于多店铺使用。
🔒 安全令牌存储：安全地保存OAuth令牌。

安装

先决条件

Node.js（建议使用18.0.0或更高版本-请参阅 package.json 发动机）
npm（通常与Node.js一起提供）或yarn

手动安装

克隆存储库 （如果您将其托管在GitHub/GitLab等上，请替换为您的存储库URL）：
```
git clone <your-repository-url>
cd etsy-mcp
```
（如果你在本地工作，你可以跳过克隆，只需 cd 进入项目目录。)
安装依赖项:
```
npm install
```
或者，如果你使用纱线：
```
yarn install
```

配置环境变量: 复制 .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

备注：The REDIRECT_URI 在你的 .env 文件（或默认值 http://localhost:3003/oauth/callback) 必须匹配为您的Etsy应用程序配置的重定向URI之一。

用法

运行服务

用于生产/内置版本:
```
npm run build
npm start
```
用于自动重新加载的开发:
```
npm run dev
```

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

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

要将此Etsy MCP服务器与类似Cursor IDE的MCP客户端一起使用，通常需要提供JSON配置。

在光标设置中，导航到MCP选项卡，单击“+添加新的全局MCP服务器”，然后输入：

{
    "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:
- 替换 YOUR_ETSY_API_KEY_HERE 和 YOUR_ETSY_CLIENT_SECRET_HERE 如果您不想依赖，请使用您的实际凭据 .env 正在被拾取的文件 npm run dev 脚本的环境。通常最好让服务器从其 .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 （数字，可选）：店铺的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 （数字，可选）：店铺的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。要添加图像，请先创建列表，然后使用 upload_listing_image 归还的工具 listing_id.
参数:
- shop_id （数字，可选）：店铺的ID。如果没有提供，则使用默认商店。
- listing_data （对象）：
  - title （string）：列表标题。
  - description （string）：列表描述。
  - price （数字）：挂牌价格（例如25.99）。
  - quantity （number）：可用数量。
  - who_made （string）：例如，“i_ded”、“collective”、“someone_else”。
  - when_made （字符串）：例如，“made_to_order”、“2020_2024”、“1950_1959”。
  - taxonomy_id （number）：列表类别的数字ID。
  - shipping_profile_id （number，可选）：装运配置文件的数字ID。如果需要 type 是“物理的”。
  - type （枚举：“物理”、“数字”、“下载”）：列表类型。
退货:

{
  "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 （数字，可选）：店铺的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 （数字，可选）：店铺的ID。如果没有提供，则使用默认商店。
- title （string）：装运配置文件的标题（例如，“美国标准”）。
- origin_country_iso （字符串，长度2）：原产国的ISO代码（例如“US”）。
- primary_cost （number，min 0）：仅运送到此目的地的成本。
- secondary_cost （数字，最小值0）：与另一个项目一起运输的成本。
- min_processing_time （整数，最小值1）：处理订单的最短天数。
- max_processing_time （整数，最小值1）：处理订单的最长天数。
- destination_country_iso （字符串，长度2，可选）：特定目的地国家的ISO代码。
- destination_region （枚举：“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 （数字，可选）：店铺ID。如果没有提供，则使用默认值。
- listing_id （整数）：要添加图像的列表的ID。
- file_name （string）：位于服务器中的图像文件的名称（例如“my_image.jpg”） public/uploads/listing_images 目录。
- 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}"
    }
  ]
}

运作原理

客户端请求：MCP客户端向此服务器发送工具调用请求（例如，通过 stdio 在本地运行时）。
身份验证检查：对于需要身份验证的工具，服务器使用以下命令检查有效的OAuth令牌 TokenStorage.
OAuth流（如果需要）: a.如果不存在有效令牌 authenticate 该工具通常由客户端调用（或由服务器指示）。 b EtsyMCPServer 呼叫 OAuthServer 生成Etsy授权URL（使用PKCE）。 c.用户在浏览器中打开此URL并授权应用程序。 d.Etsy重定向到 OAuthServer的带有授权码的回调端点。 e.The OAuthServer 使用PKCE代码验证器将代码交换为访问令牌和刷新令牌。 f.代币（包括 user_id 并可能违约 shop_id 和 shop_name)通过以下方式保存 TokenStorage.
API调用：The EtsyMCPServer 使用 EtsyApiClient （其持有访问令牌）以对Etsy V3 API进行所请求的API调用。
令牌刷新：如果访问令牌过期， getValidAccessToken() 在……里面 EtsyMCPServer 尝试使用刷新令牌来获取新的访问令牌。
响应：Etsy API的响应经过处理，并以标准MCP格式返回给MCP客户端。

故障排除

身份验证错误/授予无效:
- 确保您的 ETSY_API_KEY, ETSY_CLIENT_SECRET 在……里面 .env 是正确的。
- 确认 REDIRECT_URI 由服务器使用（默认 http://localhost:3003/oauth/callback 或如所述 .env)与Etsy应用程序设置中配置的“回调URL”之一完全匹配。
- 过期代币：尝试清算 tokens.json 从您的令牌存储路径（请参见 TokenStorage.ts 或你的 ETSY_MCP_TOKEN_PATH env-var）并重新进行身份验证。
EADDRINUSE 用于OAuth服务器：这意味着OAuth回调服务器的端口（默认3003）已在使用中。停止其他进程或配置其他进程 ETSY_MCP_OAUTH_PORT 在你的 .env 文件并相应地更新Etsy应用程序的重定向URI。
找不到用于上传图像的文件：确保 file_name 提供给 upload_listing_image 存在于 public/uploads/listing_images/ 相对于项目根目录的目录。
日志文件：检查在中生成的日志文件 logs 目录（或 ETSY_MCP_LOG_PATH)查看详细的错误消息。每次运行都会创建一个带时间戳的日志文件。

许可证

MIT许可证（如果您选择此许可证，请创建一个包含MIT许可证文本的许可证文件，或指定另一个许可证。）

Etsy API MCP服务

使用说明

Etsy MCP服务器

概述

特性

安装

先决条件

手动安装

用法

运行服务

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

api参考

`authenticate()`

`set_default_shop()`

`get_default_shop()`

`get_listings(shop_id?: number)`

`get_shop_details(shop_id?: number)`

`create_listing(shop_id?: number, listing_data: object)`

`list_shop_shipping_profiles(shop_id?: number)`

`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)`

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

运作原理

故障排除

许可证

赞助商

使用说明

Etsy MCP服务器

概述

特性

安装

先决条件

手动安装

用法

运行服务

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

api参考

authenticate()

set_default_shop()

get_default_shop()

get_listings(shop_id?: number)

get_shop_details(shop_id?: number)

create_listing(shop_id?: number, listing_data: object)

list_shop_shipping_profiles(shop_id?: number)

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)

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

运作原理

故障排除

许可证

赞助商

相关 MCP

任务管理协议服务器

Dynamics 365商业中央模型协议服务器

Shopware MCP集成演示

Kroger 购物 MCP 服务器

按需印刷自动化服务

电商链接转换服务

`authenticate()`

`set_default_shop()`

`get_default_shop()`

`get_listings(shop_id?: number)`

`get_shop_details(shop_id?: number)`

`create_listing(shop_id?: number, listing_data: object)`

`list_shop_shipping_profiles(shop_id?: number)`

`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)`

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