shopping-mcp

一个 MCP 服务器，让 Claude（或任何 MCP 客户端）能够通过官方 Browse API 搜索 eBay 商品列表。

问一句 "帮我找一把 100 美元以下的机械键盘，仅限立即购买，免运费"，助手就能真的去搜索。

eBay results for "mechanical keyboard" — showing 3 of about 41,208 matches

1. Keychron K8 Pro Wireless Mechanical Keyboard - Brown Switches — $79.99
   total $79.99 · free shipping · New · was $99.00 (19% off)
   seller keeb_supply · 99.6% positive (8421 ratings) · top rated, ships from US
   Item v1|335894120043|0 · https://www.ebay.com/itm/335894120043

2. Ducky One 3 TKL Mechanical Keyboard RGB Hot-Swappable — $84.50
   total $92.45 · $7.95 shipping · New
   seller pc_parts_direct · 98.9% positive (3310 ratings) · accepts offers
   Item v1|326770118254|0 · https://www.ebay.com/itm/326770118254

它能做什么——以及它刻意不做什么

每个工具都是只读的。 这个服务器只负责搜索和读取商品列表。它不能出价、加入购物车、下单或花钱。当你想购买时，它会给你一个商品链接，由你自己完成结账。

它基于官方 eBay Browse API 构建——不抓取网页、不进行浏览器自动化、不重放 cookie。它不会因页面布局变化而失效，也不会让你违反 eBay 的使用条款。

Related MCP server: ebay-mcp

工具

关于 search_ebay 有两点值得了解，因为这是 eBay 特有的、固定价格商品目录所不具备的：

• buying_option 可筛选为 auction、buy_it_now 或 accepts_offers。

• sort: "ending_soonest" —— 与 buying_option: "auction" 结合使用，就能找到即将结束的拍卖。

获取 API 密钥

1. 在 developer.ebay.com/my/keys 登录。

2. 创建一个应用并打开 Production 密钥集。

3. 复制 App ID（Client ID） 和 Cert ID（Client Secret）。

仅此而已。此服务器使用 OAuth 客户端凭证流程，因此你不需要用户令牌、重定向 URI 或 "RuName"。

新注册的开发者账户可能需要先通过 eBay 的验证，密钥页面才会开放——这通常大约需要一个工作日。

安装

git clone https://github.com/Kirat5690/shopping-mcp.git

cd shopping-mcp && npm install && npm run build

连接到客户端

Claude Code

claude mcp add shopping --env EBAY_CLIENT_ID=your-app-id --env EBAY_CLIENT_SECRET=your-cert-id -- node /absolute/path/to/shopping-mcp/dist/index.js

Claude Desktop

编辑 claude_desktop_config.json：

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shopping": {
      "command": "node",
      "args": ["C:\\path\\to\\shopping-mcp\\dist\\index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your-app-id",
        "EBAY_CLIENT_SECRET": "your-cert-id",
        "EBAY_MARKETPLACE_ID": "EBAY_US"
      }
    }
  }
}

重启客户端，然后让它运行 check_ebay_connection 以确认凭证可用。

配置参考

关于数字的说明

• 排序依据是含运费总价。 按价格排序时使用商品价格加上运费，因此一件便宜但邮费昂贵的商品不会因为技术性原因而胜出。eBay 自身的价格排序并不总是这样做。

• 部分商品没有总价。 当 eBay 将运费标记为结账时计算时，在知道收货地址之前不存在含运费总价，商品页面会如实说明而不是猜测。

• 不进行货币换算。 价格以市场所在地区的货币显示，与 eBay 返回的完全一致。

• 商品列表是独立的销售记录，不是目录条目。 两条标题几乎相同的搜索结果可能在成色、捆绑内容或地区上有所不同。在将它们视为同一商品之前值得仔细检查。

• find_deals 只能看到有广告折扣的商品。 它基于 eBay 的划线"原价"进行筛选，因此一件真正便宜但从未宣称有折扣的商品不会出现在结果中。

开发

npm test

测试套件无需任何 eBay 凭证即可运行。它覆盖了金额和含运费总价逻辑、输出格式化，以及一个端到端的 MCP 协议测试——该测试通过 stdio 启动服务器，并验证工具注册、schema 校验以及未配置凭证的路径。

npm run watch      # recompile on change
npm run typecheck  # types only, no emit

目录结构：

src/
  index.ts     server entry point and stdio wiring
  tools.ts     MCP tool definitions
  ebay.ts      Browse API client and OAuth token cache
  config.ts    environment parsing and marketplace table
  money.ts     price parsing, landed totals, ranking
  format.ts    human-readable output
  http.ts      fetch with timeout and retry

关于范围的说明

早期版本还通过 Product Advertising API 支持 Amazon。该功能在 v0.2.0 中被移除：PA-API 需要一个已获批准的 Amazon Associates 账户，而且如果账户没有产生符合条件的销售，Amazon 会撤销访问权限——这对大多数人来说门槛太高，导致服务器根本无法运行。

Amazon 客户端及其 AWS SigV4 签名已保留在 git 历史中，位于标签 v0.1.0-amazon 处，如果你有已获批准的账户并希望恢复该功能，可以从中找回。

许可证

MIT —— 参见 LICENSE。

与 eBay 无关联、未获其认可或赞助。你对 eBay API 的使用受 eBay API 许可协议 约束。