eBay Browse

ebay-mcp

Give an AI agent real, live market prices — straight from the largest secondhand marketplace on the internet.

eBay is a continuously-updating ledger of what physical things actually cost right now. This wraps its Browse API as an MCP server with three tools, so an agent can search listings, pull a single item, and — the useful one — get an aggregated price landscape for anything: min, median, max, broken down by condition.

Python 3.12+ · MIT · MCP server · app-token auth, no user login

Setup is one free eBay app keyset — no user login, no OAuth consent screen to click through. Point an agent at it and ask "what does an RTX 5080 actually go for?" — one call back comes a grounded answer, split by condition, with the cheapest listings attached.

---

Contents

• The three tools
• Architecture: one client, three tools
• Authentication: client-credentials, cached
• ebay_price_check: how the landscape is built
• Install
• Configuration
• Sandbox vs. production
• Project layout
• License

---

The three tools

// 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": "…" } ] }

---

Architecture: one client, three tools

Every tool flows through a single EbayBrowseClient, which owns the token and talks to eBay. There's one place credentials are read, one place a token is cached, one place HTTP happens — nothing to drift.

flowchart LR

Agent(["AI agent / Claude"]) subgraph server["ebay-mcp · stdio server"] Tools["ebay_search ebay_get_item ebay_price_check"] Client["EbayBrowseClient"] Cache[("OAuth token in-memory, auto-refresh")] end Cfg["~/.ebay-mcp.toml 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

The server is async; the client is plain synchronous requests, run in a thread (asyncio.to_thread) so a slow eBay call never blocks the event loop. ebay_price_check is the one tool that does more than pass through — it runs a search and then aggregates the result (see below).

---

Authentication: client-credentials, cached

eBay's Browse API uses an application token (the OAuth client-credentials grant) — no user is involved. The client mints one on first use, caches it in memory, and silently refreshes when it's about to expire. You never think about it.

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 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 Authorization: Bearer … B-->>C: listings JSON C-->>T: parsed results

The 60-second buffer means a token is treated as expired slightly early, so a call never races a token that dies mid-flight. Tokens live ~2 hours; in practice one fetch covers a long session.

---

ebay_price_check: how the landscape is built

The other two tools are thin wrappers. This one is the reason the project exists: it turns a pile of raw listings into a number you can reason about.

flowchart LR

Q["query

• exclude[]"] --> S["search

(up to 50 listings)"] S --> F["drop excluded titles

• unpriced listings"] F --> G["group by condition"] G --> A["aggregate

min · median · max"] G --> H["cheapest N (the tail)"] A --> R(["{ count, min, median, max, by_condition, cheapest }"]) H --> R

exclude is what makes the number honest — a search for "RTX 5080" is full of laptops and prebuilt PCs, and exclude: ["laptop", "notebook", "prebuilt"] strips them so the median reflects the actual card. The by_condition split matters just as much: a "median" that blends new-in-box with used-and-abused is noise; split by condition and each tier tells the truth.

One honest limitation worth knowing: the Browse API returns **active asking

prices**, not completed sales. Treat the floor as "best currently advertised,"

not "what it sold for."

---

Install

git clone https://github.com/cunicopia-dev/ebay-mcp

cd ebay-mcp python3.12 -m venv .venv && source .venv/bin/activate pip install -e .

You need a (free) eBay developer application keyset — see docs/SETUP.md for the five-minute walkthrough. Then wire it into your MCP client:

{

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

---

Configuration

Credentials come from environment variables (highest priority) or a `~/.ebay-mcp.toml` file. The active env selects the keyset *and* the API base URL together — so production creds can never accidentally point at the sandbox, or vice versa.

flowchart TD

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

Check what's active any time — credentials are masked in the output:

ebay-mcp-config

env: production

app_id: Keit****87dd

cert_id: PRD-****0914

api_base: https://api.ebay.com

OK — configuration is valid.

---

Sandbox vs. production

Flip env between sandbox and production to switch environments — same code, different endpoints and keyset. The sandbox is good for proving the auth flow wires up; its inventory is sparse and seeded, so for real prices you want a production keyset.

---

Project layout

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

---

License

MIT