内容
# Etsy MCP 服务器
本项目通过模型上下文协议（MCP）公开了 Etsy API 的一部分。它允许工具从 MCP 客户端调用以检索商店数据和管理商品列表。
基于 [profplum700/etsy-mcp-server](https://github.com/profplum700/etsy-mcp-server)（MIT 许可）。此版本跟踪 Etsy API 的变化，原版本已过时：
- `x-api-key` 头部现在需要 `keystring:sharedSecret` 格式（Etsy 变更，2026-02）
- `readiness_state_id`（处理配置文件）对于实物商品必填（Etsy 变更，2025-06），并提供列出和创建处理配置文件的工具
- `createDraftListing`/`updateListing` 接受 `tags`、`materials`、`shipping_profile_id`、`return_policy_id`、`shop_section_id` 和 `type`，并对数组字段使用正确的逗号分隔编码
- 新增工具：`getShopShippingProfiles`、`getShopReturnPolicies`、`getShopReadinessStateDefinitions`、`createShopReadinessStateDefinition`
## OAuth 设置
服务器需要有效的 Etsy API 密钥字符串、共享密钥和 OAuth 刷新令牌。你可以通过以下两种方式提供这些凭证：
1. **环境变量**：设置 `ETSY_API_KEY`、`ETSY_SHARED_SECRET` 和 `ETSY_REFRESH_TOKEN`。
2. **设置文件**：通过复制 `etsy_mcp_settings.example.json` 并填写你的凭证来创建 `etsy_mcp_settings.json` 文件。默认情况下，该文件在项目根目录中查找；设置 `ETSY_SETTINGS_PATH` 以使用其他位置。
如果你还没有刷新令牌，请运行以下辅助脚本：
```bash
npx tsx src/get-refresh-token --keystring YOUR_KEY --shared-secret YOUR_SECRET
```
脚本会打开一个浏览器窗口进行身份验证，并将刷新令牌打印到控制台。
## 本地开发
这些说明适用于直接在你的机器上运行服务器以进行开发目的。
首先，安装依赖项：
```bash
npm install
```
然后，构建服务器：
```bash
npm run build
```
你也可以使用 `npm run watch` 在代码更改时自动重建服务器。
### 配置文件位置
在本地开发过程中，将你的 `etsy_mcp_settings.json` 文件放在项目根目录（与 `package.json` 同级）。服务器将自动检测并加载它。
### 运行服务器
构建完成后，使用以下命令启动服务器：
```bash
npm start
```
**重要**：此 MCP 服务器通过 stdio 通信，设计用于与 MCP 客户端（如 Claude Desktop、Cline 或其他 MCP 兼容应用程序）连接。当直接运行时，它将启动并等待 MCP 协议消息。要测试功能，请使用 MCP Inspector（参见调试部分）或将其连接到 MCP 客户端。
### MCP 客户端集成
要将此服务器与 MCP 客户端一起使用，你通常需要：
1. **Claude Desktop**：将服务器配置添加到你的 Claude Desktop 设置中
2. **Cline**：在你的 MCP 服务器设置中配置服务器
3. **其他 MCP 客户端**：参考你的客户端文档以添加 MCP 服务器
当需要时，MCP 客户端将自动启动服务器。
## 使用 Docker 运行
这是部署或在标准化环境中运行服务器的推荐方法。
### 快速开始 Docker
```bash
docker build -t etsy-mcp-server .
```
### Docker 配置文件位置
在使用 Docker 时，你的 `etsy_mcp_settings.json` 文件应位于运行 `docker run` 命令的同一目录中。 `./` 在卷挂载中指的是你的当前工作目录。
### 容器行为
**重要**：MCP 服务器不是长时间运行的后台服务。当你启动容器时，它将：
1. 加载你的 Etsy 凭证（从环境变量或设置文件）
2. 打印"Etsy MCP 服务器运行在_stdio"
3. 在标准输入上等待 MCP 协议消息
4. 在短时间内退出，如果没有 MCP 客户端连接
这是正常行为。容器设计用于在需要时由 MCP 客户端启动，而不是像 Web 服务器一样连续运行。
### 启动容器
你可以提供你的 Etsy 凭证作为环境变量或挂载你的设置文件。
**选项 1：使用环境变量**
**Bash：**
```bash
docker run --rm \
-e ETSY_API_KEY=YOUR_KEY \
-e ETSY_SHARED_SECRET=YOUR_SECRET \
-e ETSY_REFRESH_TOKEN=YOUR_TOKEN \
etsy-mcp-server
```
**PowerShell：**
```powershell
docker run --rm `
-e ETSY_API_KEY=YOUR_KEY `
-e ETSY_SHARED_SECRET=YOUR_SECRET `
-e ETSY_REFRESH_TOKEN=YOUR_TOKEN `
etsy-mcp-server
```
**选项 2：使用设置文件**
在当前目录中创建 `etsy_mcp_settings.json` 文件。然后，使用 `-v` 标志将它挂载到容器中：
**Bash：**
```bash
docker run --rm \
-v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json \
etsy-mcp-server
```
**PowerShell：**
```powershell
docker run --rm `
-v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json `
etsy-mcp-server
```
### 使用 Docker 进行 MCP 客户端集成
要将此 Docker 容器与 MCP 客户端一起使用：
1. **Claude Desktop**：在你的 Claude Desktop 设置中配置服务器以使用 Docker 命令
2. **Cline**：将 Docker 命令设置为你的 MCP 服务器启动命令
3. **其他 MCP 客户端**：使用适当的 Docker 命令作为服务器可执行文件
示例 MCP 客户端配置：
```json
{
"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 进行更轻松的管理：
1. 将 `.env.example` 复制到 `.env` 并填写你的凭证：
```bash
cp .env.example .env
# 编辑 .env 文件以包含你的 Etsy API 凭证
```
2. 使用 Docker Compose 启动：
```bash
docker-compose --profile production up
```
### 生产部署
**多平台构建**（适用于 ARM64/Apple Silicon）：
```bash
# 为多个架构构建
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 .
```
**注册表部署**:
```bash
# 为注册表标记
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 故障排除
**常见问题：**
1. **容器立即退出**：这是 MCP 服务器在没有客户端连接时的正常行为
2. **权限被拒绝**：确保 Docker 具有适当的文件系统访问权限
3. **设置文件未找到**：检查卷挂载路径是否与文件位置匹配
4. **环境变量未加载**：验证 `.env` 文件语法和变量名称
**调试命令：**
```bash
# 检查容器日志
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
```
## 可用工具
### 商店
| 工具 | 描述 |
| --- | --- |
| `getMe` | 关于认证用户的信息，包括 `user_id` 和 `shop_id`。无参数。 |
| `getShop` | 获取商店信息。需要 `shop_id`。 |
| `getShopSections` | 列出商店的章节。需要 `shop_id`。 |
| `getShopShippingProfiles` | 列出运输配置。在创建实物商品时使用返回的 `shipping_profile_id`。 |
| `getShopReturnPolicies` | 列出退货政策。`return_policy_id` 在某些地区（例如欧盟）创建实物商品时必填。 |
| `getShopReadinessStateDefinitions` | 列出处理配置文件。自 2025-06 起，`readiness_state_id` 创建实物商品必填。 |
| `createShopReadinessStateDefinition` | 创建处理配置文件（`ready_to_ship` 或 `made_to_order`，带有最小/最大处理时间）。 |
### 商品列表
| 工具 | 描述 |
| --- | --- |
| `getListingsByShop` | 列出商店的商品列表，带有可选的 `state` 过滤器（`active`、`draft` 等）。 |
| `createDraftListing` | 创建草稿商品列表。必填：`shop_id`、`title`、`description`、`price`、`quantity`、`who_made`、`when_made`、`taxonomy_id`。实物商品还需要 `shipping_profile_id` 和 `readiness_state_id`。可选：`tags`、`materials`、`return_policy_id`、`shop_section_id`、`type`。 |
| `updateListing` | 更新商品列表：`title`、`description`、`price`、`tags`、`materials`、`shipping_profile_id`、`shop_section_id`。 |
| `uploadListingImage` | 将图像文件上传到商品列表。需要 `shop_id`、`listing_id` 和本地 `image_path`。 |
| `getListingImages` | 列出商品列表的图像。 |
| `getListingFiles` | 列出数字商品列表的文件。 |
| `getListingInventory` | 获取商品列表的库存详情。 |
| `updateListingInventory` | 替换商品列表的库存（`products` 数组）。 |
### 卖家分类法
| 工具 | 描述 |
| --- | --- |
| `getSellerTaxonomyNodes` | 检索卖家分类法节点的完整层次结构。 |
| `getPropertiesByTaxonomyId` | 列出特定分类法节点支持的产品属性。需要 `taxonomy_id`。 |
## 调试
### 使用 MCP Inspector
为了调试和测试服务器功能，请在 **本地开发设置** 中使用 MCP Inspector：
```bash
npm run inspector
```
Inspector 将：
1. 启动代理服务器和 Web 界面
2. 启动本地构建的 MCP 服务器
3. 提供一个 URL 以查看通信日志并交互式测试工具
**重要**：MCP Inspector 仅适用于本地开发设置，不适用于 Docker。这是因为:
- Docker 容器在没有 MCP 客户端连接时快速启动和退出
- Inspector 需要直接访问服务器进程
- 网络隔离阻止 Inspector 与容器化的服务器通信
### 推荐的调试工作流程
1. **开发和测试**：使用本地开发和 MCP Inspector
```bash
npm run build
npm run inspector
```
2. **部署**：使用 Docker 和 MCP 客户端
```bash
docker build -t etsy-mcp-server .
# 然后与你的 MCP 客户端一起使用
```
这种方法为您提供了两者的最佳选择：本地交互式调试和可靠的 Docker 部署。
