eBay Browse

ebay-mcp

让 AI Agent 获取真实、即时的市场价格——数据直接来自互联网上最大的二手交易平台。

eBay 是一本持续更新的账簿，记录着实物当前的实际价格。本项目将其 Browse API 封装为 MCP 服务，提供三个工具，让 Agent 可以搜索商品列表、获取单个商品详情，还能——最实用的一项——获取任何商品的汇总价格概况：按成色分类，展示最低价、中位数和最高价。

Python 3.12+ · MIT · MCP 服务 · 应用令牌认证，无需用户登录

只需一个免费的 eBay 应用密钥组——无需用户登录，也不用点击 OAuth 授权同意页面。将 Agent 指向该服务，询问“RTX 5080 实际卖多少钱？”——一次调用即可获得有据可依的答案，按成色分类，并附上最便宜的商品列表。

---

目录

• 三个工具
• 架构：一个客户端，三个工具
• 认证：客户端凭据，带缓存
• ebay_price_check：如何构建价格概况
• 安装
• 配置
• 沙盒与生产环境
• 项目布局
• 许可证

---

三个工具

工具	功能
ebay_price_check	获取查询结果的汇总价格概况——商品数量、最低价／中位数／最高价、按成色分类的价格明细，以及最便宜的商品列表。这是核心工具。
ebay_search	搜索商品列表并进行排序和筛选——返回规范的 {itemId, title, price, condition, seller, itemWebUrl} 行。
ebay_get_item	按 ID 获取单个商品的完整详情。

// ebay_price_check  ·  query: "RTX 5080", exclude: ["laptop", "notebook"]
{
  "count": 47, "currency": "USD",
  "min": 899, "median": 1099, "max": 2200,
  "by_condition": {
    "New":  { "count": 18, "min": 1099, "median": 1199, "max": 1634 },
    "Used": { "count": 21, "min": 899,  "median": 1050, "max": 1499 }
  },
  "cheapest": [ { "price": 899, "condition": "Used", "title": "…", "itemWebUrl": "…" } ]
}

---

架构：一个客户端，三个工具

所有工具都通过单个 EbayBrowseClient 运行，由它管理令牌并与 eBay 通信。凭据只在一个地方读取，令牌只在一个地方缓存，HTTP 请求也只在一个地方执行——一切井然有序。

flowchart LR
    Agent(["AI agent / Claude"])
    subgraph server["ebay-mcp · stdio server"]
        Tools["ebay_search<br/>ebay_get_item<br/>ebay_price_check"]
        Client["EbayBrowseClient"]
        Cache[("OAuth token<br/>in-memory, auto-refresh")]
    end
    Cfg["~/.ebay-mcp.toml<br/>or env vars"]
    eBay["eBay Browse API"]

    Agent -->|"MCP tool call"| Tools
    Tools -->|"search / get_item"| Client
    Client <-->|"reuse or mint token"| Cache
    Client -->|"Bearer token + query"| eBay
    eBay -->|"listings JSON"| Client
    Cfg -.->|"keyset + active env"| Client

服务端是异步的；客户端则使用普通的同步 requests，并在线程中运行（asyncio.to_thread），因此缓慢的 eBay 调用不会阻塞事件循环。ebay_price_check 是唯一不只是转发请求的工具——它会先执行搜索，再汇总结果（见下文）。

---

认证：客户端凭据，带缓存

eBay 的 Browse API 使用应用令牌（OAuth 客户端凭据授权）——无需用户参与。客户端会在首次使用时生成令牌，将其缓存在内存中，并在令牌即将过期时自动刷新。你无需操心。

sequenceDiagram
    participant T as Tool call
    participant C as EbayBrowseClient
    participant O as eBay OAuth
    participant B as Browse API

    T->>C: search("RTX 5080")
    alt token missing or expired
        C->>O: POST /identity/v1/oauth2/token<br/>Basic(app_id:cert_id), grant=client_credentials
        O-->>C: access_token + expires_in
        Note over C: cache until (expires_in − 60s)
    end
    C->>B: GET /item_summary/search<br/>Authorization: Bearer …
    B-->>C: listings JSON
    C-->>T: parsed results

60 秒缓冲意味着令牌会略微提前被视为过期，因此调用不会遇到令牌在执行过程中失效的情况。令牌有效期约为 2 小时；实际使用中，一次获取即可支撑较长时间的会话。

---

ebay_price_check：市场图景的构建方式

另外两个工具只是简单封装。这个工具才是项目存在的理由：它将一堆原始商品列表转化为一个可供分析的数字。

flowchart LR
    Q["query<br/>+ exclude[]"] --> S["search<br/>(up to 50 listings)"]
    S --> F["drop excluded titles<br/>+ unpriced listings"]
    F --> G["group by condition"]
    G --> A["aggregate<br/>min · median · max"]
    G --> H["cheapest N<br/>(the tail)"]
    A --> R(["{ count, min, median, max,<br/>by_condition, cheapest }"])
    H --> R

exclude 能让数字更可信——搜索 "RTX 5080" 会出现大量笔记本电脑和预装整机，而 exclude: ["laptop", "notebook", "prebuilt"] 会将它们剔除，让中位数反映显卡的实际价格。按 by_condition 分类同样重要：“中位数”若混合了全新未拆封和饱经使用的商品，就毫无参考价值；按成色分类后，各档价格才能反映真实情况。

有一个值得了解的限制：Browse API 返回的是当前在售标价，而非已完成的交易价格。请将最低价理解为“当前标出的最低价格”，而不是“实际成交价”。

---

安装

git clone https://github.com/cunicopia-dev/ebay-mcp
cd ebay-mcp
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .

你需要一个免费的 eBay 开发者应用密钥集——请参阅 docs/SETUP.md，其中有一份五分钟快速指南。然后将其接入你的 MCP 客户端：

{
  "mcpServers": {
    "ebay": { "command": "/path/to/ebay-mcp/.venv/bin/ebay-mcp" }
  }
}

---

配置

凭据来自环境变量（优先级最高）或 ~/.ebay-mcp.toml 文件。当前的 env 会同时选择密钥集和 API 基础 URL，因此生产环境凭据绝不会意外指向沙盒，反之亦然。

flowchart TD
    Start(["load_config()"]) --> Env{"EBAY_ENV /<br/>EBAY_*_APP_ID<br/>in environment?"}
    Env -->|"set"| UseEnv["take keyset<br/>from env vars"]
    Env -->|"unset"| Toml{"~/.ebay-mcp.toml<br/>present?"}
    Toml -->|"yes"| UseToml["take keyset<br/>from TOML"]
    Toml -->|"no"| Default["default env = production<br/>(error if creds missing)"]
    UseEnv --> Pick["env → keyset + base URL<br/>(locked together)"]
    UseToml --> Pick
    Default --> Pick

# ~/.ebay-mcp.toml   (chmod 600)
env = "production"

[production]
app_id  = "YourApp-PRD-..."
cert_id = "PRD-..."

[sandbox]
app_id  = "YourApp-SBX-..."
cert_id = "SBX-..."

随时检查当前启用的配置——输出中的凭据会经过掩码处理：

ebay-mcp-config
# env:      production
# app_id:   Keit****87dd
# cert_id:  PRD-****0914
# api_base: https://api.ebay.com
# OK — configuration is valid.

---

沙盒与生产环境

在 sandbox 和 production 之间切换 env 即可更换环境——代码相同，但端点和密钥集不同。沙盒适合验证身份验证流程是否正常接通；其中的商品库存稀少且为预置数据，因此要查询真实价格，请使用生产环境密钥集。

---

项目结构

src/ebay_mcp/
  config.py    # env + TOML loader; ebay-mcp-config CLI
  browse.py    # EbayBrowseClient — OAuth cache + search / get_item
  server.py    # MCP server: list_tools / call_tool / main
tests/         # config precedence, aggregation, tool listing (no network)
docs/SETUP.md  # getting an eBay keyset

---

许可证

MIT