Etsy-MCP服务器

Name: Etsy-MCP服务器
Author: profplum700

作者：profplum7008 星标更新：2025-07-13

安装使用来源：spider==github.com

项目介绍

Etsy MCP Server

该项目通过模型上下文协议（Model Context Protocol）公开了Etsy API的一部分。它允许工具从MCP客户端调用以检索商店数据和管理列表。

OAuth配置

服务器需要有效的Etsy API密钥字符串、共享密钥和OAuth刷新令牌。你可以通过以下两种方式提供这些凭证：

环境变量：设置ETSY_API_KEY、ETSY_SHARED_SECRET和ETSY_REFRESH_TOKEN。
设置文件：复制etsy_mcp_settings.example.json并填写你的凭证，创建一个etsy_mcp_settings.json文件。

如果你还没有刷新令牌，可以运行以下辅助脚本：

npx tsx src/get-refresh-token --keystring YOUR_KEY --shared-secret YOUR_SECRET

该脚本会打开浏览器窗口进行身份验证，并在控制台中打印刷新令牌。

本地开发

这些说明是用于直接在你的机器上运行服务器进行开发目的。

首先，安装依赖项：

npm install

然后，构建服务器：

npm run build

你也可以使用npm run watch来自动重建服务器，当你修改代码时。

配置文件位置

对于本地开发，将你的etsy_mcp_settings.json文件放置在项目根目录下（与package.json同级）。服务器会自动检测并加载它。

运行服务器

构建后，启动服务器：

npm start

重要：此MCP服务器通过标准输入输出通信，并设计为由MCP客户端连接（如Claude Desktop、Cline或其他兼容MCP的应用程序）。直接运行时，它将启动并等待MCP协议消息。要测试功能，请使用MCP Inspector（参见调试部分）或将其连接到MCP客户端。

MCP客户端集成

要使用此服务器与MCP客户端，通常需要：

Claude Desktop：在你的Claude Desktop设置中添加服务器配置
Cline：在你的MCP服务器设置中配置服务器
其他MCP客户端：参考你的客户端文档以添加MCP服务器

当需要时，MCP客户端会自动启动服务器。

使用Docker运行

这是推荐的部署方法，或者在标准化环境中运行服务器。

快速开始使用Docker

选项1：本地构建

docker build -t etsy-mcp-server .

选项2：从注册表拉取（当可用时）

# 未来：docker pull etsy-mcp-server:latest

Docker使用中的配置文件位置

对于Docker使用，你的etsy_mcp_settings.json文件应位于你运行docker run命令的同一目录中。卷挂载中的./指的是你的当前工作目录。

容器行为

重要：MCP服务器不是长时间运行的后台服务。当你启动容器时，它将：

加载你的Etsy凭证（来自环境变量或设置文件）
打印"Etsy MCP服务器正在标准输入输出上运行"
在标准输入上等待MCP协议消息
如果没有MCP客户端连接，将在短时间内退出

这是正常的行为。容器设计为在需要时由MCP客户端启动，而不是像Web服务器那样持续运行。

启动容器

你可以通过环境变量或挂载设置文件来提供你的Etsy凭证。

选项1：使用环境变量

Bash:

docker run --rm \
  -e ETSY_API_KEY=YOUR_KEY \
  -e ETSY_SHARED_SECRET=YOUT_SECRET \
  -e ETSY_REFRESH_TOKEN=YOUR_TOKEN \
  etsy-mcp-server

PowerShell:

docker run --rm `
  -e ETSY_API_KEY=YOUR_KEY `
  -e ETSY_SHARED_SECRET=YOUR_SECRET `
  -e E  TSY_REFRESH_TOKEN=YOUR_TOKEN `
  etsy-mcp-server

选项2：使用设置文件

在你的当前目录中创建一个etsy_mcp_settings.json文件。然后，使用-v标志将其挂载到容器中：

Bash:

docker run --rm \
  -v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json \
  etsy-mcp-server

PowerShell:

docker run --rm `
  -v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json `
   etsy-mcp-server

Docker中的MCP客户端集成

要使用此Docker容器与MCP客户端：

Claude Desktop：在你的Claude Desktop设置中配置服务器以使用Docker命令
Cline：设置Docker命令作为你的MCP服务器启动命令
其他MCP客户端：使用适当的Docker命令作为服务器可执行文件

示例MCP客户端配置：

{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-v",
    "./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json",
    "etsy-mcp-server"
  ]
}

MCP客户端会在需要使用Etsy工具时自动启动容器，并在完成后停止它。

Docker Compose（推荐）

为了更方便地管理，使用Docker Compose：

复制.env.example到.env并填写你的凭证：

cp .env.example .env
# 编辑.env文件，填入你的Etsy API凭证

使用Docker Compose启动：
```
docker-compose --profile production up
```

生产部署

多平台构建（适用于ARM64/Apple Silicon）：

# 构建多个架构
docker buildx build --platform linux/amd64,linux/arm64 -t etsy-mcp-server:latest .

# 或者专门构建ARM64（Apple Silicon）
docker buildx build --platform linux/arm64 -t etsy-mcp-server:arm64 .

注册表部署：

# 标记为注册表
docker tag etsy-mcp-server:latest your-registry.com/etsy-mcp-server:1.0.0

# 推送到注册表
docker push your-registry.com/etsy-mcp-server:1.0.0

Docker故障排除

常见问题：

容器立即退出：这是没有客户端连接时MCP服务器的正常行为
权限被拒绝：确保Docker具有正确的文件系统访问权限
找不到设置文件：检查卷挂载路径是否匹配你的文件位置
环境变量未加载：验证.env文件语法和变量名称

调试命令：

# 检查容器日志
docker logs etsy-mcp-server

# 交互式运行容器进行调试
docker run -it --rm etsy-mcp-server sh

# 手动输入测试容器
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker run -i --rm etsy-mcp-server

可用工具

`getShop`

获取关于商店的信息。所需参数：shop_id。

`getMe`

返回关于已认证用户的基信息，包括user_id和 shop_id。此端点不需要任何参数。

`getListingsByShop`

列出商店中的列表。支持可选的state参数（例如active，draft）。需要shop_id。

`createDraftListing`

使用POST /v3/application/shops/{shop_id}/listings创建新的物理草稿列表。该工具接受Etsy的createDraftListing端点支持的所有字段。

`uploadListingImage`

上传图像到列表。需要shop_id，listing_id和image_path。（当前实现是一个占位符。）

`updateListing`

更新现有列表。需要shop_id和listing_id。可选字段包括title，description和price。

`getShopReceipts`

检索商店的收据。需要shop_id。

`getShopSections`

检索商店中的部分列表。需要shop_id。

`getShopSection`

根据shop_id和shop_section_id检索单个商店部分。

`getSellerTaxonomyNodes`

检索卖家分类节点的完整层次结构。

`getPropertiesByTaxonomyId`

列出特定分类节点支持的产品属性。需要taxonomy_id。

调试

使用MCP Inspector

为了调试和测试服务器功能，使用MCP Inspector与本地开发设置：

npm run inspector

Inspector将：

启动代理服务器和Web界面
启动本地构建的MCP服务器
提供一个URL以查看通信日志并交互式测试工具

重要：MCP Inspector仅适用于本地开发设置，不适用于Docker。这是因为：

当没有MCP客户端连接时，Docker容器快速启动和退出
Inspector需要直接访问服务器进程
网络隔离阻止Inspector与容器化服务器通信