# 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](https://github.com/Niki-q/product-scout-skill), 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.

## Setup

1. Register at [developer.ebay.com](https://developer.ebay.com/my/keys)
   (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:
   ```sh
   npm install
   npm test
   ```

## Register with Claude Code

```sh
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](LICENSE).