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.)

Troubleshooting

401 invalid_client / "client authentication failed" on a fresh Production keyset that looks correct. Confirmed live cause: a brand-new Production keyset shows as ready in the portal but stays functionally disabled — marked "Non Compliant" — until you resolve the Marketplace Account Deletion/Closure Notifications requirement. Go to your application → Alerts & Notifications tab, and if this server doesn't store any eBay user data (it doesn't — it's a stateless, read-only wrapper), toggle "Exempted from Marketplace Account Deletion" on and save. The keyset activates within a minute or two; no code or credential change needed, and this is not a bug in the App ID/Cert ID pair even though the error message implies bad credentials.

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. In practice a Production keyset for a simple read-only app was approved within about a day, not the "few days" eBay's own docs suggest as an upper bound — treat that as a ceiling, not an estimate.

• 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.