Ebay MCP

🚀 eBay API MCP Server

这是一个基于 Model Context Protocol (MCP) 的服务器，为AI助手提供全面访问eBay销售API的能力。它包含230多个工具，可用于库存管理、订单履行、营销活动、分析等多个方面。API覆盖率达99.1%（约111个eBay销售API端点中的110个）。

🚀 快速开始

1. 获取eBay凭证

1. 创建一个免费的 eBay开发者账户。
2. 在 开发者门户 中生成应用程序密钥。
3. 保存你的 客户端ID 和 客户端密钥。

2. 安装

选项A：从npm安装（推荐）

npm install -g ebay-mcp

选项B：从源代码安装

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
npm run build

3. 配置

运行交互式设置向导：

npm run setup

或者手动配置：

cp .env.example .env
# 使用你的凭证编辑.env文件
npm run auto-setup

4. 配置MCP客户端

将此服务器添加到你的MCP客户端配置中：

Claude桌面版： 编辑你的Claude桌面版配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

添加服务器配置：

{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_REDIRECT_URI": "your_runame"
      }
    }
  }
}

替代方案：使用本地安装版本 如果你是从源代码安装的：

{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox"
      }
    }
  }
}

5. 使用

重启你的MCP客户端（如Claude桌面版等），并通过AI助手开始使用eBay工具。

✨ 主要特性

• 230多个eBay API工具 - 全面覆盖eBay销售API，涵盖库存、订单、营销、分析等多个领域。
• OAuth 2.0支持 - 完整的用户令牌管理，支持自动刷新。
• 类型安全 - 使用TypeScript构建，结合Zod验证和OpenAPI生成的类型。
• MCP集成 - 支持STDIO传输，可直接与AI助手集成。
• 智能认证 - 当用户令牌（每天10,000 - 50,000次请求）不可用时，自动切换到客户端凭证（每天1,000次请求）。
• 测试完善 - 拥有870多个测试用例，函数覆盖率达99%以上。

📦 安装指南

安装方式

选项A：从npm安装（推荐）

npm install -g ebay-mcp

选项B：从源代码安装

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
npm run build

💻 使用示例

基础用法

以下是一些使用eBay MCP服务器可以完成的常见任务：

设置OAuth以提高速率限制

用户：“你能帮我为我的eBay账户设置OAuth认证吗？” 助手：使用 ebay_get_oauth_url 工具生成授权URL。你访问该URL并授予权限后，助手会帮助你在 .env 文件中配置刷新令牌。 结果：每天可访问10,000 - 50,000次API请求，而不是1,000次。

管理库存

用户：“显示我在eBay上的所有活跃列表” 助手：使用 ebay_get_inventory_items 工具检索所有库存项目。 结果：显示所有产品的格式化列表，包括SKU、数量和状态。

处理订单

用户：“获取过去7天内所有未完成的订单” 助手：使用 ebay_get_orders 工具，并设置日期过滤器和履行状态参数。 结果：返回一个待处理订单列表，可进行发货处理。

创建营销活动

用户：“为我的电子产品类别创建一个推广列表活动” 助手：使用 ebay_create_campaign 工具和相关营销工具设置广告活动。 结果：根据指定的预算和目标项目创建新的活动。

批量操作

用户：“将'复古手表'类别中所有商品的价格降低10%” 助手：结合使用 ebay_get_inventory_items 工具过滤类别，并使用 ebay_update_offer 工具批量更新价格。 结果：所有匹配的商品都更新为新价格。

📚 详细文档

配置

📖 如需全面的配置指南，包括所有环境变量的详细说明、OAuth流程步骤和故障排除，请参阅 配置文档。

环境变量

创建一个 .env 文件，并使用你的eBay凭证进行配置：

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox  # 或 "production"
EBAY_REDIRECT_URI=your_runame

# 可选：用于更高的速率限制（每天10,000 - 50,000次请求）
EBAY_USER_REFRESH_TOKEN=your_refresh_token

OAuth认证

客户端凭证（自动）：

• 默认认证方法
• 每天1,000次请求
• 除了客户端ID和密钥外，无需其他设置

用户令牌（生产环境推荐）：

• 每天10,000 - 50,000次请求（根据账户类型而定）
• 使用 ebay_get_oauth_url 工具生成授权URL
• 在OAuth流程完成后，将 EBAY_USER_REFRESH_TOKEN 添加到 .env 文件中
• 令牌会自动刷新

如需详细的OAuth设置和全面的配置指南，请参阅 配置文档。

MCP客户端兼容性

此服务器与任何支持STDIO传输的MCP客户端兼容：

已测试并支持的客户端：

• ✅ Claude桌面版（macOS、Windows、Linux） - 完全支持
• ✅ MCP检查器 - 用于开发和测试
• ✅ 自定义MCP客户端 - 通过STDIO或HTTP传输

配置要求：

• MCP协议版本：1.0+
• 传输方式：STDIO（默认）或HTTP
• Node.js运行时：18.0.0或更高版本

其他MCP客户端： 虽然未进行具体测试，但该服务器应该与任何符合MCP标准的客户端兼容，包括：

• Continue.dev
• 其他支持MCP的编辑器
• 自定义实现

如果你成功地将此服务器与其他MCP客户端一起使用，请通过 开启讨论 告知我们！

速率限制

了解eBay API的速率限制对于生产环境的使用至关重要：

客户端凭证（默认）：

• 每日限制：每天1,000次请求
• 适用场景：开发、测试、低流量操作
• 设置方式：只需提供客户端ID和密钥，自动配置

用户令牌（推荐）：

• 每日限制：每天10,000 - 50,000次请求（根据账户类型而定）
• 适用场景：生产环境、高流量操作
• 设置方式：需要进行OAuth流程（使用 ebay_get_oauth_url 工具）

不同账户类型的速率限制层级：

• 个人开发者：每天10,000次请求
• 商业开发者：每天25,000次请求
• 企业用户：每天50,000次以上请求（自定义限制）

速率限制最佳实践：

1. 在生产环境中使用用户令牌
2. 在遇到速率限制错误时实现指数退避策略
3. 尽可能缓存响应
4. 在eBay开发者门户中监控你的使用情况
5. 当API支持时，批量执行操作
6. 考虑升级你的开发者账户层级以获得更高的限制

处理速率限制： 当你达到速率限制时，API会返回429状态码。服务器将：

• 自动使用指数退避策略重试请求
• 通知你速率限制错误
• 建议你升级到用户令牌认证

检查当前使用情况： 在 eBay开发者门户 中监控你的API使用情况。

可用工具

服务器提供230多个工具，分为以下几类：

• 账户管理 - 策略、计划、订阅、销售税
• 库存管理 - 商品、报价、位置、批量操作
• 订单履行 - 订单、运输、退款、纠纷
• 营销与推广 - 活动、广告、促销、竞价
• 分析 - 流量报告、卖家标准、指标
• 沟通 - 买家与卖家消息、谈判
• 元数据与分类法 - 类别、商品属性、策略
• 令牌管理 - OAuth URL生成、令牌管理

工具示例：

• ebay_get_inventory_items - 列出所有库存商品
• ebay_get_orders - 检索卖家订单
• ebay_create_offer - 创建新的列表报价
• ebay_get_campaigns - 获取营销活动
• ebay_get_oauth_url - 生成OAuth授权URL

如需完整的工具列表，请参阅 src/tools/definitions/。

开发

先决条件

• Node.js >= 18.0.0
• npm或pnpm
• eBay开发者账户

设置

# 分叉并克隆仓库
git clone https://github.com/YOUR_USERNAME/ebay-mcp.git
cd ebay-mcp

# 安装依赖
npm install

# 设置环境
cp .env.example .env
# 使用你的凭证编辑.env文件

# 构建并测试
npm run build
npm test

开发命令

npm run dev              # 运行STDIO服务器
npm run dev:http         # 运行HTTP服务器
npm run test             # 运行测试
npm run test:watch       # 在监视模式下运行测试
npm run typecheck        # 类型检查代码
npm run lint             # 代码检查
npm run format           # 格式化代码

Docker支持

在容器化环境中运行服务器：

# 构建Docker镜像
npm run docker:build

# 启动容器
npm run docker:up

# 查看日志
npm run docker:logs

# 停止容器
npm run docker:down

# 重启容器
npm run docker:restart

Docker Compose配置： 可以使用Docker Compose轻松部署服务器：

docker-compose up -d

在运行Docker命令之前，应在 .env 文件中配置环境变量。容器将自动使用你的 .env 配置。

Docker使用场景：

• 生产部署
• 一致的开发环境
• CI/CD管道
• 隔离的测试环境

HTTP服务器模式

除了为MCP客户端提供的默认STDIO传输方式外，服务器还可以以HTTP模式运行，用于测试和调试：

# 开发环境
npm run dev:http

# 生产环境
npm run start:http

HTTP模式特性：

• 为所有工具提供RESTful API端点
• 交互式API文档
• 无需MCP客户端即可测试工具
• 支持CORS，适用于Web应用程序
• 包含Helmet安全头

何时使用HTTP模式：

• 在开发过程中测试单个工具
• 构建自定义集成
• 调试API响应
• 创建基于Web的界面

注意：STDIO模式（默认）推荐用于MCP客户端集成（如Claude桌面版等）。HTTP模式主要用于开发和自定义集成。

项目结构

ebay-mcp/
├── src/
│   ├── index.ts           # MCP服务器入口点
│   ├── api/               # eBay API实现
│   ├── auth/              # OAuth和令牌管理
│   ├── tools/             # MCP工具定义
│   ├── types/             # TypeScript类型
│   └── utils/             # 验证模式
├── tests/                 # 测试套件
├── docs/                  # 文档
└── build/                 # 编译输出

如需详细的贡献指南，请参阅 CONTRIBUTING.md。

贡献

欢迎贡献代码！以下是开始的步骤：

1. 分叉仓库
2. 创建一个功能分支：git checkout -b feature/my-feature
3. 进行更改并添加测试
4. 运行质量检查：npm run check && npm test
5. 使用 Conventional Commits 进行提交
6. 推送到你的分叉仓库并打开拉取请求

提交前注意事项：

• 确保所有测试通过
• 遵循TypeScript最佳实践
• 根据需要更新文档
• 保持测试覆盖率

如需详细的贡献指南，请参阅 CONTRIBUTING.md。

故障排除

常见问题

服务器未出现在Claude桌面版中

问题：eBay MCP服务器未在你的MCP客户端中显示。 解决方案：

1. 验证配置文件路径是否适用于你的操作系统
2. 检查JSON语法是否有效（使用JSON验证器）
3. 确保环境变量已正确设置
4. 完全重启Claude桌面版
5. 检查Claude桌面版日志以获取错误消息

认证错误

问题：出现“无效凭证”或“认证失败”错误。 解决方案：

1. 验证你的 EBAY_CLIENT_ID 和 EBAY_CLIENT_SECRET 是否正确
2. 确保你使用的是正确的环境（沙盒环境还是生产环境）
3. 检查你的应用程序密钥在eBay开发者门户中是否处于活动状态
4. 对于用户令牌，验证你的 EBAY_USER_REFRESH_TOKEN 是否有效
5. 运行 npm run diagnose 检查你的配置

速率限制错误

问题：出现“速率限制已超出”错误。 解决方案：

1. 升级到用户令牌认证（每天10,000 - 50,000次请求）
2. 在使用过程中实现请求限流
3. 在开发者门户中检查你当前的速率限制
4. 考虑升级你的eBay开发者账户层级

工具无法正常工作

问题：工具返回意外错误或空结果。 解决方案：

1. 验证你使用的是正确的环境（沙盒环境还是生产环境）
2. 确保你对该操作具有适当的权限和范围
3. 检查eBay API状态：https://developer.ebay.com/support/api-status
4. 运行 npm run diagnose:export 生成诊断报告
5. 查看 eBay API文档 了解端点要求

诊断工具

运行诊断程序以排查配置问题：

# 交互式诊断
npm run diagnose

# 导出诊断报告
npm run diagnose:export

诊断工具将检查：

• 环境变量配置
• eBay API连接性
• 认证状态
• 令牌有效性
• 可用的范围和权限

获取帮助

如果你仍然遇到问题：

1. 检查现有的 GitHub问题
2. 查看 GitHub讨论
3. 创建一个新问题，并提供以下信息：
   • 你的诊断报告（npm run diagnose:export）
   • 重现问题的步骤
   • 错误消息或日志
   • 你的环境（操作系统、Node版本、MCP客户端）

资源

文档

• eBay开发者门户 - API文档和凭证
• eBay API许可协议 - 使用条款和合规要求
• eBay数据处理要求 - 重要的数据保护和隐私指南
• eBay API状态 - 实时API健康和状态
• MCP文档 - 模型上下文协议规范
• OAuth快速参考 - 完整的OAuth认证指南，包括范围、故障排除和示例
• OAuth设置指南 - 详细的认证配置
• 贡献指南 - 如何为该项目贡献代码
• 行为准则 - 社区指南和期望
• 更新日志 - 版本历史和发布说明
• 安全策略 - 漏洞报告指南

支持

• GitHub讨论 - 社区问答和一般讨论
• 问题跟踪器 - 错误报告和功能请求
• 错误报告模板 - 详细的错误报告指南

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

致谢

• eBay开发者计划 提供API访问权限
• 模型上下文协议 提供MCP规范
• 所有 贡献者 帮助改进了这个项目

---

⚠️ 重要提示

在使用本软件之前，请仔细阅读以下免责声明。本项目是一个 开源项目，按“原样”提供，不提供任何形式的明示或暗示保证。使用本软件即表示您承认并同意以下内容：

• 无责任声明：本项目的作者、贡献者和维护者对使用本软件可能产生的任何损害、损失或问题 不承担任何责任，包括但不限于：数据丢失或损坏、财务损失、服务中断、eBay账户暂停或终止、违反eBay的服务条款或API使用政策，以及任何其他直接或间接损害。
• eBay API使用：本项目是一个非官方的第三方实现，与eBay公司没有关联、未得到其认可或赞助。您独自负责：遵守 eBay的API使用条款、确保您的使用在eBay的速率限制和政策范围内、安全管理您的eBay开发者凭证、理解并遵守 eBay的数据处理要求，以及通过API执行的任何操作。
• 自担风险使用：本软件仅用于教育和开发目的。用户必须：在生产使用之前在eBay的沙盒环境中进行全面测试、理解代表其进行的API调用、备份关键数据、监控其API使用和账户状态。
• 安全责任：您负责：确保您的API凭证安全、正确配置环境变量、理解MCP服务器使用的安全影响，以及遵循安全最佳实践。
• 无保证声明：本软件不保证其功能、可靠性或适用于特定目的。

使用本软件即表示您承担所有风险，并同意免除作者、贡献者和维护者的任何索赔、损害或责任。如需官方eBay API支持，请参考 eBay开发者计划。