ebay-mcp

Expose eBay's marketplace to Claude over the Model Context Protocol. Claude can search active listings, analyse price distributions, surface deals priced below the market median, and produce a market-research overview — all as structured JSON it can reason about.

It answers questions like:

• What does a used Nintendo Switch OLED actually sell for right now?
• Find me listings priced well below the going rate.
• Give me a market overview: price spread, condition mix, who's selling, and shipping.

How it works

                       OAuth2 (client credentials)
                              │
 ┌────────┐   tools    ┌──────┴───────┐   HTTPS   ┌──────────────────┐
 │ Claude │ ────────►  │  ebay-mcp    │ ────────► │ eBay Buy Browse  │
 │        │ ◄────────  │  MCP server  │ ◄──────── │ API              │
 └────────┘    JSON    └──────────────┘           └──────────────────┘

The server authenticates to eBay with the OAuth2 client-credentials grant (caching and refreshing the application token), calls the Buy Browse API, normalises the verbose responses into typed objects, and runs price/market analysis locally before handing JSON back to Claude.

The code is layered so the analysis is testable without the network:

• config.py — environment-driven configuration.
• models.py — typed value objects parsed from eBay JSON.
• auth.py — OAuth token caching/refresh (concurrency-safe).
• client.py — the only module that talks to eBay; retries + filter grammar.
• analysis.py — pure price/deal/market functions.
• server.py — the MCP tools.

Tools

Tool	What it does
search_products	Search active listings (sort, condition, price range, free-shipping filters).
analyze_prices	Price distribution for a query: min/max, mean, median, p25/p75/p90, stdev.
find_deals	Listings priced at least N% below the market median, ranked by discount.
market_research	Full overview: price stats, condition mix, price-by-condition, shipping, seller locations, observations.
get_item_details	Full details for a single listing by item id.

All prices are isolated to a single currency and, unless noted, reflect total cost (item + shipping).

Setup

Requires Python 3.10+ and an eBay developer account.

1. Create an application at https://developer.ebay.com/my/keys and copy the App ID (Client ID) and Cert ID (Client Secret).

2. Install:

   git clone https://github.com/luke-nielsen/ebay-mcp.git
   cd ebay-mcp
   python3 -m venv .venv && source .venv/bin/activate
   pip install -e ".[dev]"
   

3. Configure credentials (copy .env.example to .env, or export directly):

   export EBAY_CLIENT_ID=your-app-id
   export EBAY_CLIENT_SECRET=your-cert-id
   

4. Verify connectivity:

   ebay-mcp check
   ebay-mcp search "nintendo switch oled" --limit 5
   ebay-mcp research "airpods pro 2"
   

Connecting to Claude

Add the server to your MCP host. For Claude Code:

claude mcp add ebay -- ebay-mcp serve

Or use the bundled .mcp.json (it reads EBAY_CLIENT_ID / EBAY_CLIENT_SECRET from your environment). The server speaks MCP over stdio.

Configuration

Variable	Default	Description
EBAY_CLIENT_ID	—	App ID (Client ID). Required.
EBAY_CLIENT_SECRET	—	Cert ID (Client Secret). Required.
EBAY_ENVIRONMENT	production	production or sandbox.
EBAY_MARKETPLACE_ID	EBAY_US	e.g. EBAY_GB, EBAY_DE, EBAY_AU.
EBAY_DELIVERY_COUNTRY	—	Buyer country for shipping estimates.
EBAY_DELIVERY_POSTAL_CODE	—	Buyer postal code for shipping estimates.
EBAY_TIMEOUT	20	Per-request timeout (seconds).
EBAY_MAX_RETRIES	3	Retry attempts for transient failures.

Development

pip install -e ".[dev]"
pytest        # run the test suite
ruff check .  # lint

The networking layer is exercised with httpx.MockTransport, so the full suite runs offline and needs no credentials.

Notes & limitations

• Uses the Buy Browse API, which covers active listings. Sold/completed price history requires eBay's restricted Marketplace Insights API and is out of scope here; "market" statistics are therefore over current asking prices.
• The client-credentials token grants access to public search only — no user-specific or order data.
• eBay rate limits the Browse API (default ~5,000 calls/day); the analysis tools spend one call each.

License

MIT — see LICENSE.