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.

Related MCP server: eBay MCP Server by CData

Tools

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

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.