Ebay Mcp

eBay MCP 服务 — 让 Claude、Cursor 和任何 AI 助手全面访问 eBay 的 Sell API。提供 379 个库存、订单、营销和分析工具，使用你自己的密钥在本地运行。

_{非官方开源项目 — 与 eBay Inc. 无关联，未经其授权或认可。}

eBay MCP 是一个本地 Model Context Protocol 服务，可将 AI 助手 — Claude Desktop、Claude Code、Cursor、Cline、Windsurf、Zed、Continue.dev、Roo Code 和 Amazon Q Developer — 直接连接到 eBay 的 Sell API。它提供 379 个工具，覆盖其跟踪的 100% 的 eBay Sell、Commerce 和 Developer API（356 个不重复端点），用于库存管理、订单履行、Promoted Listings 营销、分析和开发者工具。所有内容都通过 STDIO 或本地 HTTP 在你的计算机上运行 — 无需云端中继，你的 eBay 凭据也不会离开计算机。

免责声明： 非官方第三方项目 — 与 eBay Inc. 无关联，也未获其认可。 按“原样”提供，不作任何保证。你有责任遵守 eBay API 许可协议 和数据处理要求，妥善保管凭据，并遵守速率限制。投入生产前请先在沙盒中测试。请参阅 LICENSE。

目录

• 功能
• 能力概览
• eBay MCP 与原始 eBay API 的对比
• 一键式 AI 设置
• 快速开始
• 演示
• 配置
• 可用工具
• 交互式 UI（MCP Apps）— beta
• 使用示例
• 范围与安全
• 日志与故障排查
• 常见问题
• 贡献
• 资源
• 许可证
• 贡献者

功能

• 379 个 eBay API 工具 — 全面覆盖 eBay Sell API，包括库存、订单、营销、分析、元数据、分类体系和开发者工具。
• 9 个 AI 客户端，自动配置 — Claude Desktop、Cursor、Zed、Cline、Continue.dev、Windsurf、Roo Code、Claude Code CLI 和 Amazon Q Developer。
• 内置 OAuth 2.0 — 完整的用户令牌管理，支持自动刷新，并可在用户令牌（每天 10k–50k 次请求）与客户端凭据（每天 1k 次请求）之间智能回退。
• 默认具备弹性 — 遇到 429 速率限制时自动采用指数退避重试，并清晰、一贯地呈现错误。
• 类型安全 — 全流程使用 TypeScript，工具输入经 Zod 验证，类型由 OpenAPI 生成。
• 本地优先且保护隐私 — 通过 STDIO 或本地 HTTP 运行；你的凭据和数据绝不会离开你的设备。
• 沙盒和生产环境 — 通过一个变量即可切换环境。
• 一条命令完成设置 — npm run setup 可配置凭据、OAuth 和 MCP 客户端，并自动打开浏览器进行 OAuth 流程。
• 经过充分测试 — 每次变更都会通过 GitHub Actions 在 CI 中运行 1,000 多项自动化测试。

能力地图

在决定要启用哪个工具系列，或询问助手能做什么时，请使用此地图。系列名称与 EBAY_MCP_TOOLS 相同，因此你可以启用所有工具、动态发现工具，或仅启用特定工作流所需的系列。

刊登前检查：必填商品属性

调用 ebay_create_or_replace_inventory_item、ebay_create_offer 或 ebay_get_listing_fees 前，请获取所选分类的实时要求：

ebay_get_default_category_tree_id → ebay_get_category_suggestions → ebay_get_item_aspects_for_category

属性响应会标明必填和推荐的商品属性。创建报价前，请将所有必填属性添加到库存商品中。要求会因分类和市场而异，因此任一项发生变化时都应重新查询；不要依赖示例或固定的全局备用值。

拍卖报价

ebay_create_offer、ebay_update_offer 和 ebay_bulk_create_offer 通过同一 Inventory 模型支持这两种刊登形式：

查看 ebay_get_listing_type_policies，了解类别允许的刊登形式和时长，然后在调用 ebay_publish_offer 前查看 ebay_get_listing_fees。混合两种形式的请求正文会在本地被拒绝，不会发送给 eBay。

Trading（XML）路径上的拍卖

旧版工具使用顶层 format 参数切换形式（默认为 FIXED_PRICE）。当 ebay_create_listing、ebay_revise_listing、ebay_end_listing 和 ebay_relist_item 使用 format: "AUCTION" 时，会调用支持拍卖的接口（AddItem、ReviseItem、EndItem、RelistItem），而不是 *FixedPriceItem 系列接口；ebay_create_listing 还会自动为 Item 添加 ListingType: "Chinese"：

混合请求载荷会在本地被拒绝。如果不清楚现有商品的刊登形式，请先使用 ebay_get_listing 读取其 ListingType（Chinese 表示拍卖）。

上传本地文件中的照片和视频

报价至少需要一张图片才能发布。媒体工具会通过 eBay 的 Media API 上传本地文件，并返回 Inventory API 所需的信息：

默认禁止访问本地文件：设置 EBAY_MCP_MEDIA_DIRS（以路径分隔符分隔的目录）和／或 EBAY_MCP_MEDIA_ROOT（一个目录，也用于解析 media://<relative-path> 引用）以允许访问。执行包含性检查前会先解析符号链接；任何位于允许目录之外的文件都会在上传前被拒绝。支持的格式：JPG、PNG、GIF、BMP、TIFF、WEBP、AVIF、HEIC，最大 12 MB；MP4/MOV，最大 150 MB。未使用的上传文件会在 eBay 端过期；刊登使用后便会永久保留。

图片 URL 和文档

这八个工具也属于 inventory 系列：

对于刊登手册，调用 ebay_create_document，并传入 {"documentType":"USER_GUIDE_OR_MANUAL","languages":["ENGLISH"]}，然后调用 ebay_upload_document，并传入返回的 documentId 和 "path":"media://manual.pdf"。或者，调用 ebay_create_document_from_url， 并传入相同的元数据以及 "documentUrl":"https://example.com/manual.pdf"。 使用 ebay_get_document 确认状态为 ACCEPTED 后，再将 ID 关联到 刊登。调用这些工具需要用户同意 sell.inventory，包括读取操作。

刊登文档支持 PDF、JPEG/JPG 和 PNG，大小不超过 10 MiB（10,485,760 字节）。 售后文档还支持 BMP 和 GIF，大小限制为 5 MiB（5,242,880 字节）。 本地上传使用上述相同的媒体允许列表，并会检查扩展名和文件签名。不支持 动画/多页 PNG；多页内容请使用 PDF。eBay 会根据用途限制 PDF 页数。

对于退货标签，调用 ebay_upload_post_order_document，并传入 {"path":"media://label.pdf","documentUsageType":"RETURN_SHIPPING_LABEL","entityType":"RETURNS","entityId":"YOUR_RETURN_ID"}。 初始状态为 SUBMITTED；发布需要单独调用 eBay GraphQL mutation，无法通过这些工具完成。 已提交文档仅所有者可下载；已发布文档需要在售后流程中获得授权后才能下载。 已发布文档无法删除，过期文档不可用。

售后工具需要符合条件的密钥集，并需要用户同意 https://api.ebay.com/oauth/api_scope/commerce.post_order.document。 将其添加到现有的 EBAY_OAUTH_SCOPES 列表中，然后重新执行 OAuth 设置/授权。 该变量会替换请求的 scope 列表，因此请保留你需要的其他 scope。 刷新令牌不会授予额外的 scope。系统可识别此 scope，但不会将其添加到默认授权请求中。 所有 Media API POST 操作均受 eBay 用户级限制：每五秒最多 50 个请求；速率限制错误会 返回给调用方。

请参阅 eBay 的 Media API 概览 和发行说明。

财务、信息流、商店和运输标签

这些系列涵盖了 Sell API 的其余部分：Finances、Feed、Stores、Logistics 和 Account v2，以及之前缺失的 Metadata 运输、Taxonomy 和 Charity 端点：

异步变更。 Feed 任务和商店分类变更会返回从 eBay 的 Location 标头中读取的 taskId（Feed 计划会返回 scheduleId）。轮询 ebay_get_feed_task 或 ebay_get_store_task，直到任务完成，然后获取任何结果文件。eBay 同一时间只允许一个商店分类变更在处理中。

文件输入和输出。 下载内容（Feed 输入、结果和计划文件、运输标签及 Taxonomy 属性导出）会以嵌入式 MCP 资源的形式返回，包含 base64 字节；不会写入磁盘。一旦确定文件大小超过 25 MiB，就会立即报错，不再读取其余内容。EBAY_US 等大型市场的属性导出会超过此限制，因此应按分类使用 ebay_get_item_aspects_for_category。ebay_upload_feed_task_file 会通过与媒体工具相同的 EBAY_MCP_MEDIA_DIRS / EBAY_MCP_MEDIA_ROOT 允许列表，读取最大 15 MiB（eBay 数据文件限制）的本地 .xml、.csv、.zip 或 .gz 文件。

资金流转。 ebay_create_shipment_from_shipping_quote 会购买邮资并向卖家的账单协议收费；ebay_cancel_shipment 会在标签未使用时退款。

可选范围。 系统识别以下两个范围，但默认从不请求：

• 三个订单收入工具所需的 https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read。
• 所有 Logistics 工具所需的 https://api.ebay.com/oauth/api_scope/sell.logistics；该 API 仅限有限发布。

符合条件的密钥集需将该范围添加到 EBAY_OAUTH_SCOPES，同时保留所需的其他范围，然后重新进行 OAuth 授权。

数字签名（欧盟／英国卖家）。 对于注册地在欧盟或英国的卖家，eBay 要求每次 Finances API 调用以及 issueRefund 都使用 数字签名；否则 eBay 会返回 403 Missing x-ebay-signature-key header。启用签名的方法：

1. 运行 ebay_create_signing_key（建议使用 ED25519）并保存响应 — eBay 不会再次显示私钥。
2. 将其 jwe 设置为 EBAY_SIGNING_KEY_JWE，将其 privateKey 设置为 EBAY_SIGNING_PRIVATE_KEY（使用返回的 base64 值或 PEM 密钥），然后重启服务。

此后，这些调用会携带 x-ebay-signature-key、Content-Digest、Signature-Input 和 Signature 标头（RFC 9421）。其他调用从不签名，且在这两个变量未设置时不会有任何变化。通过 EBAY_MCP_API_BASE_URL 转发时，调用会针对其实际访问的 eBay 主机和路径（api.ebay.com 或 apiz.ebay.com）进行签名，因此代理必须转发 eBay 的 Host 标头和原始 eBay 路径。

eBay MCP 与原始 eBay API

两者都与相同的 eBay 端点通信——区别在于，你不必再自行构建其他所有内容。

一键式 AI 设置

让 AI 助手为你完成设置。 复制下方提示词，并将其粘贴到 Claude、ChatGPT 或任何支持 MCP 的 AI 助手中。

I want to set up the eBay MCP Server for my AI assistant. Please help me:

1. Install the eBay MCP server:
   npm install -g ebay-mcp

2. I need to configure it for [Claude Desktop / Cursor / Cline / Zed / Continue.dev / Windsurf / Claude Code CLI / Amazon Q] (choose one)

3. My eBay credentials are:
   - Client ID: [YOUR_CLIENT_ID]
   - Client Secret: [YOUR_CLIENT_SECRET]
   - Environment: [sandbox / production]
   - Redirect URI (RuName): [YOUR_REDIRECT_URI]

Please:
- Create the appropriate config file for my MCP client
- Set up the environment variables
- Help me complete the OAuth flow to get a refresh token for higher rate limits
- Test that the connection works

If I don't have eBay credentials yet, guide me through creating a developer account at https://developer.ebay.com/

快速开始

1. 获取 eBay 凭据

1. 创建免费的 eBay Developer Account。
2. 在 Developer Portal 中生成应用密钥。
3. 保存你的 Client ID 和 Client Secret。

2. 安装

npm install -g ebay-mcp            # from npm (recommended)

或从源代码安装：

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

3. 运行设置向导

npm run setup

该向导会配置你的 eBay 凭据、设置 OAuth（以获得更高的速率限制）、自动检测并配置你的 MCP 客户端，并自动保存所有设置。

4. 使用只读请求进行验证

重启 MCP 客户端并询问：

“检查我的 eBay API 速率限制。”

这应该会调用 ebay_get_rate_limits 或 ebay_get_user_rate_limits，确认服务、凭据和 MCP 客户端配置正常，且不会更改卖家数据。

5. 开始使用

通过 AI 助手开始管理 eBay。先从只读问题开始，确认目标环境是沙盒还是生产环境后，再使用会修改库存、订单或推广活动的工具。

演示

通过 Claude Desktop 查看 eBay MCP Server 的实际演示：

https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b

配置

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox            # or "production"
EBAY_REDIRECT_URI=your_runame
EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
# EBAY_SITE_ID=0                    # Trading API site override; defaults from EBAY_MARKETPLACE_ID
EBAY_CONTENT_LANGUAGE=en-US         # default request content language
EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
# EBAY_SIGNING_KEY_JWE=<jwe>         # Digital Signatures for EU/UK sellers (jwe from ebay_create_signing_key)
# EBAY_SIGNING_PRIVATE_KEY=<key>     # privateKey from the same response (base64 PKCS#8 or PEM)
EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)
EBAY_READ_ONLY=false                # when true, only register read-only tools (gets/lists/searches)
# Local photo/video upload (optional — off until a directory is allowed):
# EBAY_MCP_MEDIA_DIRS=/srv/media    # path-delimited directories the media and feed upload tools may read
# EBAY_MCP_MEDIA_ROOT=/srv/media    # root for media://<relative-path> references (also allowed)
# HTTP deploy (optional — Docker / Railway / self-hosted):
# MCP_HOST=0.0.0.0                  # default is 0.0.0.0 when PORT is set
# MCP_PORT=3000                     # preferred over platform PORT
# MCP_AUTH_TOKEN=secret             # static Bearer for HTTP MCP (skips OAuth verifier)
# MCP_CORS_ORIGINS=https://app.example.com  # browser origins allowed cross-origin (comma-separated); default: loopback origins only

可用工具

常见任务，可以像向 AI 助手提出请求那样表述：

• 设置 OAuth — “帮我为 eBay 账号设置 OAuth。” → 通过 ebay_get_oauth_url 生成授权 URL，然后配置刷新令牌。每天可处理 10k–50k 个请求。
• 管理库存 — “显示我所有在售的商品。” → ebay_get_inventory_items 会返回 SKU、数量和状态。
• 为商品刊登添加照片 — “将 ~/listings/megadrive 中的三张照片添加到 SKU MD-001。” → ebay_attach_media_to_inventory_item 会将照片上传至 eBay Picture Services，并更新 product.imageUrls（设置 EBAY_MCP_MEDIA_DIRS 即可允许访问该文件夹）。
• 发起拍卖 — “将这个 SKU 刊登为 7 天拍卖，起拍价 $9.99，保留价 $25。” → 使用 format: "AUCTION"、auctionStartPrice、auctionReservePrice 和 listingDuration: "DAYS_7" 调用 ebay_create_offer，然后调用 ebay_publish_offer。对于旧版流程，使用 format: "AUCTION" 和 Trading Item（StartPrice、ReservePrice、ListingDuration: "Days_7"）调用 ebay_create_listing。
• 查询报价 — ebay_get_offers 会返回一个必填 SKU 对应的报价。若要列出整个库存中的报价，先调用 ebay_get_inventory_items，然后针对每个 SKU 调用一次 ebay_get_offers。
• 管理配送政策 — “创建一个配送政策，然后更新其处理时间。” → ebay_create_fulfillment_policy 会创建可重复使用的政策 ID，ebay_update_fulfillment_policy 会替换其设置。
• 处理订单 — “获取过去 7 天内所有未完成配送的订单。” → 使用日期和配送状态筛选条件调用 ebay_get_orders。
• 创建营销活动 — “为电子产品创建推广刊登营销活动。” → 使用 ebay_create_campaign 和相关营销工具。
• 批量操作 — “为所有‘Vintage Watches’商品打 10% 的折扣。” → 对匹配项调用 ebay_get_inventory_items + ebay_update_offer。

范围与安全

• 非官方项目。 这不是 eBay 产品，也不会授予超出你自己的 eBay Developer 账号所拥有权限的任何额外 API 权限。
• 本地服务，实时 API。 MCP 服务在你的计算机上运行，但工具仍会通过互联网调用 eBay 的沙盒或生产环境 API。
• 会修改数据的工具可能更改卖家数据。 库存、配送、营销、账号、feed、商店和 Trading 工具可能会创建、修改、退款、结束或以其他方式更新 eBay 记录，而 ebay_create_shipment_from_shipping_quote 会购买邮资。请先在沙盒中测试。
• 工具暴露范围可配置。 如果需要更精简、适用于特定工作流的工具集，可使用 EBAY_MCP_TOOLS=dynamic 或指定工具系列列表。
• 交互式视图为只读。 MCP Apps 视图可以翻页、刷新并深入查看读取类工具，但不会修改 eBay 数据。
• 合规责任由你承担。 请妥善保管凭证、监控速率限制，并遵守 eBay 的 API 条款和数据处理规则。

日志记录与故障排查

• 日志记录 — 基于 Winston，写入 stderr（符合 MCP 安全要求），也可选择输出到文件。
• 故障排查 — 服务未显示、身份验证错误、速率限制、结果为空。请先运行 npm run diagnose。

常见问题

参与贡献

欢迎贡献。Fork → 创建分支 → 添加测试 → 运行下方检查 → 使用 Conventional Commits 规范提交 → 发起 PR。

pnpm typecheck && pnpm typecheck:mcp-apps   # TypeScript (server + MCP Apps views)
pnpm check:ci                              # Biome lint + format
pnpm test && pnpm test:integration         # Vitest unit + integration
pnpm build                                 # Build to build/

推送前，若要在 Docker 中本地运行 CI 检查，可使用 act：act workflow_dispatch -W .github/workflows/ci.yml。机器上的 ~/.actrc 用于选择运行器、架构和共享缓存。

资源

项目文档：

• llms.txt — 面向 AI Agent 的精简项目概要。
• Releases 和 Issue Tracker。

官方规范和工具：

• eBay Developer Portal、Sell API docs、API License Agreement、Data Handling Requirements 和 API Status。
• Model Context Protocol 和 MCP Apps SDK。
• Node.js、npm package、TypeScript、Zod、Effect、Biome、Vitest 和 GitHub Actions。
• Claude Code 和 llms.txt。

许可证

MIT — 详见 LICENSE。

贡献者

感谢所有帮助改进此项目的人！🎉