Etsy MCP服务器
一个模型上下文协议（MCP）服务器，公开Etsy Open API v3，使Manus等人工智能代理能够以编程方式管理Etsy商店、列表、订单和库存。
概述
该MCP服务器提供了AI代理和Etsy API之间的桥梁，允许自动管理：
- 商店：查看和管理店铺信息
- 列表：创建、更新、删除和发布产品列表
- 图像：上传和管理列表图像
- 库存：管理产品变体、数量和定价
- 订单：查看和完成客户订单（收据）
- 运输：管理运输档案和跟踪
- 分类学：浏览Etsy的产品类别
特性
- ✅ 完整的Etsy Open API v3集成
- ✅ OAuth 2.0身份验证
- ✅ 16种全面的车间管理工具
- ✅ TypeScript实现
- ✅ 与MCP SDK 0.5.0兼容+
- ✅ 生产就绪错误处理
先决条件
- Node.js 18+或Node.js 20+
- Etsy卖家账户
- Etsy API应用程序（注册地址：https://www.etsy.com/developers/your-apps)
- OAuth 2.0访问令牌
安装
1.克隆或下载
git clone
cd etsy-mcp-server2.安装依赖项
npm install3.注册你的Etsy应用程序
- 首选https://www.etsy.com/developers/your-apps
- 点击“创建新应用”
- 填写所需信息：
- 应用程序名称：选择描述性名称 - 应用程序说明：描述您的集成 - 重定向URI: http://localhost:3000/oauth/callback （或您的回调URL）
- 提交并获取您的 API密钥（密钥字符串）
4.获取OAuth 2.0访问令牌
Etsy需要OAuth 2.0身份验证。您需要完成授权流程以获取访问令牌。
使用OAuth辅助脚本的快速方法：
npm run oauth这将指导您完成OAuth流程并保存您的令牌。
手动方法：
看 OAUTH_GUIDE.md 有关手动完成OAuth流的详细说明，请参阅文件。
5.配置环境
创建一个 .env 文件：
cp .env.example .env编辑 .env 并添加您的凭据：
ETSY_API_KEY=your_api_keystring_here
ETSY_ACCESS_TOKEN=your_oauth_access_token_here
ETSY_REFRESH_TOKEN=your_refresh_token_here6.建设项目
npm run build用法
本地运行
发展：
npm run dev生产：
npm start连接到Manus
要将此MCP服务器与Manus一起使用，请在MCP设置中进行配置：
{
"mcpServers": {
"etsy": {
"command": "node",
"args": ["/path/to/etsy-mcp-server/dist/index.js"],
"env": {
"ETSY_API_KEY": "your_api_key",
"ETSY_ACCESS_TOKEN": "your_access_token"
}
}
}
}可用工具
MCP服务器为Etsy商店管理提供了16个工具：
车间管理
get_shops：列出与您的帐户关联的所有商店get_shop：获取特定商店的详细信息
上市管理
get_shop_listings：列出商店中的所有商品（带过滤器）get_listing：获取特定列表的详细信息create_draft_listing：创建新的列表草稿update_listing：更新现有列表delete_listing：删除列表
图像管理
upload_listing_image：将图像上传到列表get_listing_images：获取列表的所有图像
库存管理
get_listing_inventory：获取列表的库存详细信息update_listing_inventory：更新库存（变量、数量、价格）
订单管理
get_shop_receipts：列出商店的订单（收据）get_receipt：获取特定订单的详细信息update_receipt_tracking：向订单添加跟踪信息
目录和运输
get_seller_taxonomy：获取Etsy的产品类别层次结构get_shipping_profiles：获取商店的配送配置文件
示例工作流
1.创建和发布列表
用户： “为手工陶瓷杯创建新的列表”
代理工作流程：
get_shops→ 获取shop_idget_seller_taxonomy→ 找到合适的类别（taxonomy_id）get_shipping_profiles→ 获取shipping_profile_idcreate_draft_listing→ 创建列表upload_listing_image→ 添加产品照片update_listing→ 将状态设置为“活动”以进行发布
2.完成订单
用户： “通过美国邮政发送订单号12345，跟踪号9400123456789”
代理工作流程：
get_shops→ 获取shop_idget_receipt→ 验证订单详细信息update_receipt_tracking→ 添加跟踪信息
3.更新库存
用户： “我还有10个蓝色杯子”
代理工作流程：
get_listing_inventory→ 获取当前库存结构update_listing_inventory→ 更新蓝色变体的数量
OAuth令牌管理
访问令牌过期
Etsy访问令牌在以下时间到期 1小时。令牌过期时，服务器将返回身份验证错误。
刷新令牌
上次刷新令牌 90天 并且可以用于在没有用户交互的情况下获得新的访问令牌。
要刷新您的访问令牌，请执行以下操作：
npm run refresh-token或者在应用程序中实现自动刷新（请参见 OAUTH_GUIDE.md).
API费率限制
Etsy对API请求强制执行速率限制：
- 每秒10个请求 每个API密钥
- 每天10000个请求 每个API密钥
如果超过这些限制，MCP服务器将返回速率限制错误。在代理逻辑中实现适当的限制。
错误处理
服务器包括全面的错误处理：
- OAuth错误（401）-令牌过期或无效
- 速率限制错误（429）-请求太多
- 未找到错误（404）-资源不存在
- 验证错误（400）-参数无效
所有错误都会返回描述性消息，以帮助调试问题。
发展
项目结构
etsy-mcp-server/
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript (generated)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env.example # Example environment variables
├── .gitignore
└── README.md建筑
npm run build观看模式
对于自动重建的开发：
npm run watch故障排除
“ETSY_API_KEY环境变量是必需的”
确保您已创建 .env 使用Etsy开发人员门户中的API密钥进行文件。
“ETSY_ACCESS_TOKEN环境变量是必需的”
您需要完成OAuth 2.0流程以获取访问令牌。跑 npm run oauth 或按照中的手册说明进行操作 OAUTH_GUIDE.md.
身份验证错误（401）
您的访问令牌可能已过期（持续1小时）。使用刷新令牌获取新的访问令牌，或重新运行OAuth流。
速率限制错误（429）
您已超过Etsy的API费率限制。请稍候，然后重试，或实施请求限制。
创建列表时“taxonomy_id无效”
使用 get_seller_taxonomy 工具为您的产品查找有效的类别ID。
安全考虑
- 永远不要承诺你的
.env文件 到版本控制 - 将API密钥和令牌安全地存储在环境变量中
- 定期轮换访问令牌（1小时后过期）
- 部署到生产环境时使用HTTPS
- 将OAuth范围限制为仅需要的范围
OAuth范围
此服务器需要以下OAuth作用域：
listings_r-阅读列表listings_w-创建/编辑列表listings_d-删除列表shops_r-阅读店铺信息shops_w-更新店铺设置transactions_r-读取订单/收据transactions_w-更新订单（跟踪等）
您可以根据需要自定义OAuth流中的作用域。
部署
此MCP服务器可以部署到任何Node.js托管平台。看 部署.md 有关以下内容的详细说明：
- 不锈钢（建议用于MCP服务器）
- Heroku
- 铁路
- AWS Lambda
- Docker/Kubernetes
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
资源
支持
对于以下问题：
______________________________________________________________________
内置❤️ Etsy卖家社区