ebay-browse-mcp

Minimal MCP server for searching eBay listings via the Browse API. Communicates over stdio JSON-RPC, so it works with any MCP-compatible host (Claude Desktop, Claude Code, Cursor, VS Code Copilot, Cline, Continue, Zed, Windsurf, LM Studio, Goose, and others).

Features

• Two tools: search_ebay (keyword, filters, sort, pagination) and get_item_details (full item record by ID)

• OAuth 2.0 client credentials flow, token cached in memory

• Sandbox or production via a single env var

• Pure Python, no framework lock-in beyond the official MCP SDK

Install

git clone https://github.com/<your-username>/ebay-browse-mcp.git
cd ebay-browse-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Configure

1. Create an eBay developer account at https://developer.ebay.com

2. Generate an Application Keyset (both sandbox and production keysets are available)

3. Enable OAuth for the keyset on the eBay developer portal

4. Copy .env.example to .env and fill in your credentials:

cp .env.example .env
nano .env

EBAY_CLIENT_ID=your_app_id_here
EBAY_CLIENT_SECRET=your_cert_id_here
EBAY_MARKETPLACE=EBAY_GB
EBAY_ENV=sandbox

Sandbox vs production

• EBAY_ENV=sandbox routes requests to api.sandbox.ebay.com. Sandbox listings are synthetic test data, not real inventory. Start here to verify your OAuth flow and integration end-to-end with no approval friction.

• EBAY_ENV=production routes to api.ebay.com and returns real eBay listings. To use production you must:

  1. Use the production keyset credentials (different CLIENT_ID and CLIENT_SECRET than sandbox)

  2. Comply with eBay's marketplace account deletion notification process, or apply for an exemption if you do not store eBay user data

  3. Enable OAuth on the production keyset

Switching environments is a one-line change to .env. The credentials for each environment are separate and not interchangeable.

Test the client directly

.venv/bin/python ebay_client.py "macbook pro m4 max 64gb"

Expected output: a list of items with title, price, and URL.

Register with your MCP host

The server speaks stdio JSON-RPC. Add it to your host's MCP configuration with two values:

• command: absolute path to the venv Python (/absolute/path/to/ebay-browse-mcp/.venv/bin/python)

• args: ["/absolute/path/to/ebay-browse-mcp/server.py"]

Claude Desktop / Claude Code / Cursor / Windsurf / LM Studio / Cherry Studio / Goose

These hosts share the mcpServers JSON shape. Add the block below to the relevant config file and restart the host.

{
  "mcpServers": {
    "ebay-browse": {
      "command": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/ebay-browse-mcp/server.py"
      ]
    }
  }
}

Config file locations:

VS Code Copilot

VS Code uses servers (not mcpServers) under the mcp section of settings.json:

{
  "mcp": {
    "servers": {
      "ebay-browse": {
        "command": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/ebay-browse-mcp/server.py"]
      }
    }
  }
}

Zed

Zed uses context_servers in ~/.config/zed/settings.json:

{
  "context_servers": {
    "ebay-browse": {
      "command": {
        "path": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/ebay-browse-mcp/server.py"]
      }
    }
  }
}

Continue, Cline and others

Continue (~/.continue/config.json) uses an mcpServers array; Cline uses cline_mcp_settings.json with the same shape as Claude Desktop. Check your host's documentation for the exact file path. The command and args are always the same.

Once registered, restart the host and the search_ebay and get_item_details tools become available.

Tool: search_ebay

Returns a list of items. Each item includes an item_id field (format v1|<numeric>|0) that can be passed to get_item_details for the full record.

Filter examples

Combine with commas: price:[800..3500],priceCurrency:GBP,itemLocationCountry:GB.

Full reference: https://developer.ebay.com/api-docs/buy/static/ref-buy-browse-filters.html

Tool: get_item_details

Returns the full item record: title, description, item specifics (aspects), all images, condition, brand, MPN, category path, buying options, availability, seller details, item location, shipping options with estimated delivery dates, and return terms.

Typical chain: an LLM calls search_ebay to find candidates, then get_item_details on the promising ones to read full descriptions or shipping costs before recommending.

Project structure

ebay-browse-mcp/
├── .env.example         template; copy to .env
├── .gitignore
├── README.md
├── requirements.txt
├── evaluation.xml       10 read-only LLM eval questions
├── ebay_client.py       Browse API client (no MCP dependency)
└── server.py            FastMCP server, wraps ebay_client.search_items

Evaluation

evaluation.xml contains 10 read-only questions designed for LLM evaluation harnesses. Questions target stable response properties (shape, field values, filter behaviour) rather than specific listings, because eBay inventory changes constantly. Each question has a single verifiable string answer.

Comparison with similar projects

Three open-source eBay MCP servers exist as of mid-2026. They target different use cases. Pick the one that fits yours:

Pick ebay-browse-mcp (this project) if: you want an LLM to search eBay listings with filters (price range, condition, location, sort), with minimal setup and a small surface area. The goal is a focused tool that does one thing well.

Pick YosefHayim/ebay-mcp if: you run an eBay store and want an LLM to manage your inventory, fulfil orders, run marketing campaigns, or pull analytics. It is the most complete Sell-API integration available.

Pick CooKey-Monster/EbayMcpServer if: you want the absolute minimum dependency footprint and only need a single keyword lookup. Note that the repo has not been updated for over a year as of mid-2026.

License

MIT