ebay-browse-mcp

An MCP server wrapping eBay's official Browse API — no browser, no cookies, no bot-check. Built as the eBay backend for product-scout, whose Playwright-based eBay scraping kept hitting eBay's bot-check interstitial. The Browse API is free, uses app-level OAuth (not a user login), and returns real per-country shipping costs directly.

Tools

• ebay_search_items — keyword search (item_summary/search). Returns candidates with title, price, condition, canonical URL, and a coarse shipping estimate. Not verified yet — see the next tool.

• ebay_get_item — full item detail (getItem) for one itemId from a search result, including shippingOptions with the real shipping cost for the requested country. This is the verification + shipping-cost step product-scout-skill requires before presenting any result.

Both tools accept an optional country (2-letter ISO code — this project targets CY, UA, MD, but any code eBay recognizes works), which is sent as eBay's X-EBAY-C-ENDUSERCTX: contextualLocation=country=<CC> header so prices/shipping reflect that destination.

Related MCP server: ebay-mcp

Setup

1. Register at developer.ebay.com (free). Create an Application Keyset — you get a Sandbox keyset immediately; Production requires eBay's review, which can take a few days, so start with Sandbox.

2. From that keyset, take the App ID (Client ID) and Cert ID (Client Secret). The Browse API OAuth scope (https://api.ebay.com/oauth/api_scope) is the default client-credentials scope — nothing extra to request.

3. Copy .env.example to .env and fill in:

   EBAY_APP_ID=...
   EBAY_CERT_ID=...
   EBAY_ENV=sandbox        # or "production" once you have production keys
   EBAY_MARKETPLACE_ID=EBAY_US   # required by the API; EBAY_US is a fine default

4. Install and smoke-test:

   npm install
   npm test

Register with Claude Code

claude mcp add ebay-browse -- node --env-file=/path/to/ebay-browse-mcp/.env /path/to/ebay-browse-mcp/index.js

(or add the equivalent entry to your .mcp.json — command: "node", args: ["--env-file=/path/to/ebay-browse-mcp/.env", "/path/to/ebay-browse-mcp/index.js"]; alternatively skip --env-file and put EBAY_APP_ID etc. directly in the config's env block, whichever your MCP host supports.)

Notes

• Sandbox vs. Production data are entirely separate catalogs — Sandbox returns eBay's seeded test listings, not real items. Use Sandbox to confirm the plumbing works, then switch EBAY_ENV=production (once approved) for real searches.

• Default rate limit is 5,000 calls/day per application (not per user) — ample for personal shopping research; request a limit increase from the developer portal if that's ever not enough.

• The access token is cached in memory and refetched automatically once it expires (eBay tokens last ~2 hours) — no manual refresh needed.

License

MIT — see LICENSE.