Etsy Seller MCP Hub

Etsy Seller MCP Hub

Etsy 官方 MCP 注册表

面向 Etsy 卖家的开源 MCP 服务。 使用 AI 助手、脚本或本地应用管理自己的 Etsy 店铺中的商品刊登、订单、库存、个性化选项和媒体。基于 Etsy Open API v3 构建，提供 79 个 MCP 工具、一个 CLI 和一个本地 HTTP 网关。

这是一个面向卖家的店铺管理工具包，不会监控消费者价格、搜索买家优惠或自动购物。

首次设置 · 安全审查 · 连接器故障排除 · MCP 配置 · 卖家工作流演示 · 现有 API 密钥 · 托管与隐私 · 路线图 · Glama 列表 · 常见问题 · 目录

“Etsy”一词是 Etsy, Inc. 的商标。本应用使用 Etsy 的 API，但并未获得 Etsy 的认可或认证。

卖家可以做什么？

• 查看在售商品刊登和库存；检查订单、交易、店铺数据和配送设置。
• 更新已获批准的商品刊登、库存和个性化选项；上传商品图片、视频或文件。
• 通过 79 个 MCP 工具使用 Etsy 当前的 Open API v3 端点，并可按需执行高级原始 API 操作。
• 使用 etsyctl CLI、本地 HTTP API 或兼容的 AI 客户端运行相同的卖家工作流。

提示词示例：“我的哪些在售商品库存不足？”，“按 ID 显示已付款但尚未发货的订单”，“检查商品刊登 123456789 的个性化选项”，“准备这些商品刊登变更供我审批”。

面向卖家的只读工作流：etsy_report_low_stock（范围受限的库存扫描）和 etsy_report_unshipped（尽量减少客户数据）。对应的 CLI 命令：etsyctl report low-stock 和 etsyctl report unshipped。

接口	适用对象	状态
本地 MCP（stdio）	Claude Desktop、Cursor 和其他兼容客户端	可用
CLI / etsyctl	脚本、卖家自动化和后端 Agent	可用
本地 HTTP / GPT Actions	卖家集成	可用
通过 HTTPS 连接的远程 MCP	私有、仅限所有者使用的 ChatGPT 连接器	已实现，受限
面向多个互不相关店铺的公共服务	多租户 SaaS 运营方	尚未实现

快速开始

Etsy 授权和操作系统相关详情，请参阅分步指南。

需要 Node.js 22+、已获批准的 Etsy Open API v3 应用和已授权凭据。

从 npm 安装

从 npm 安装公开发布的包：

npm install -g etsy-seller-mcp-hub
etsyctl init --shop-id 12345678    # replace with your actual shop ID
etsyctl doctor                    # inspect local config, then enter your own credentials
# Complete Etsy OAuth as documented in docs/QUICKSTART.md
etsy-mcp

npm 包名为 etsy-seller-mcp-hub。首次使用时，请在 MCP 客户端配置中添加 ETSY_MCP_READ_ONLY=1。安装后提供的命令仍为 etsy-mcp（本地 MCP 服务）和 etsyctl（CLI）。

从源代码运行

git clone https://github.com/Bl0ck154/etsy-seller-mcp-hub.git
cd etsy-seller-mcp-hub
cp config.example.json /tmp/etsy-seller-config.json
# Edit shop_id, credential paths, and local backup paths in the copied JSON.
export ETSY_HUB_CONFIG=/tmp/etsy-seller-config.json
node bin/etsyctl.mjs shops
node bin/etsy-mcp.mjs

配置示例使用 Linux 文件系统路径。请将其替换为适用于你计算机的绝对路径；切勿提交密钥或令牌。shops 命令会列出已配置的店铺别名，而实时店铺操作需要 OAuth。请参阅 credentials.example.json 和 MCP 客户端设置。

CLI 示例

etsyctl --help
etsyctl doctor
etsyctl report low-stock --threshold 3 --limit 10 --offset 0
etsyctl report unshipped --limit 20 --offset 0

卖家报告为只读，不会在已付款／未发货摘要中返回买家联系信息。

高级 CLI 示例

etsyctl listing list active --limit 100
etsyctl listing get 1234567890
etsyctl inventory get 1234567890
etsyctl orders list --limit 20 --paid true
etsyctl personalization get 1234567890
etsyctl images list 1234567890
etsyctl request GET /application/shops/12345678/sections

我的旧版 Etsy API 密钥还能用吗？

可以，前提是它是现有的 Etsy Open API v3 已获批准密钥，并且你拥有所需的 OAuth 授权。 Etsy 于 2026 年 7 月推出的 Seller App 等级，为新店主提供了更简单的审批途径。Etsy 明确表示，已经持有 Personal Key 的卖家不符合新等级的申请资格，因为其现有密钥提供了相当的访问权限。

MCP 为 AI 客户端提供接口，但不会改变 Etsy 的权限。我们不会运营一个收集其他卖家 Etsy 令牌的共享服务。Seller App 仅限自有店铺使用。为无关联卖家运营同一服务的开发者需要合适的 Etsy 访问权限（Personal App，且可能需要 Commercial Access）以及安全的多租户 OAuth，而此代码库目前尚未实现这些功能。每位可自托管用户都必须配置自己的已授权凭据。

请阅读 Etsy API 访问：现有密钥、Seller App 和 Commercial Access。

身份验证与安全

Etsy v3 要求在 x-api-key 标头中提供 keystring 和 shared secret。访问卖家私有数据或执行写入操作还需要 OAuth 2.0 作用域。该 hub 支持 OAuth PKCE、令牌刷新、重试和速率限制。要授权你的店铺：

etsyctl oauth start --shop main --redirect https://your-registered-callback.example/oauth/callback
etsyctl oauth complete --state STATE --code CODE

OAuth 授权后，该 hub 会验证配置的店铺是否归你所有。请勿从会轮换刷新令牌的其他程序中复制刷新令牌。

对于本地 HTTP：

ETSY_HUB_CONFIG=/absolute/path/config.json node src/server.mjs

该服务默认绑定到 127.0.0.1，没有内部 bearer 令牌时会拒绝外部绑定。如需远程使用，请添加经过身份验证的 TLS 和适当的访问控制。现有的远程 MCP OAuth 支持一个由所有者批准的私有 ChatGPT 客户端，不支持一般第三方卖家登录。

公开的可自托管 MCP 在完整模式下会公开 79 个工具。设置 ETSY_MCP_READ_ONLY=1 可仅公开 53 个标注为只读的工具。要启用写入功能，请移除只读变量、授予必要的 Etsy OAuth 写入作用域，并重新授权你自己的店铺。启用完整访问的步骤。这是额外的工具筛选，不可替代 Etsy OAuth 权限。对于受支持的类型化商品刊登、库存和媒体写入操作，系统会创建备份；原始 API 写入不会自动创建快照。向 AI 客户端授予写入访问权限前，请确认任何实时修改。

Docker

docker build -t etsy-seller-mcp-hub:local .
docker run --rm --name etsy-seller-mcp-hub -p 127.0.0.1:3737:3737 -v /absolute/etsy-data:/data:rw -e ETSY_HUB_CONFIG=/data/config.json etsy-seller-mcp-hub:local

在 Docker 中，将 server.host 设置为 0.0.0.0，并配置非空的 server.auth_token_file，否则启动时会拒绝外部绑定。仅在本地主机上公开主机端口，或将其置于经过身份验证的 HTTPS 后方。Dockerfile 以非 root 用户运行。

开发

npm run check
npm test
npm pack --dry-run --ignore-scripts

测试使用模拟对象，不会写入线上店铺。请参阅贡献指南、安全和 MIT 许可证。

© 2026 Bl0ck154。用于已授权 Etsy 卖家集成的独立开源软件。

默认情况下，每个请求的分块媒体上传最多可包含 64 MiB 的解码后文件。配置 ETSY_HUB_MAX_UPLOAD_BYTES（单位为字节，最大 192 MiB）可上传更大的文件。本地文件路径的分块上传现在以 64 KiB 为单位进行流式传输；来自远程 MCP 的 base64 JSON 上传仍采用缓冲方式，并受大小限制。