shopping-mcp

An MCP server that lets Claude (or any MCP client) search eBay listings through the official Browse API.

Ask "find me a mechanical keyboard under $100, buy-it-now only, free shipping" and the assistant can actually go and look.

eBay results for "mechanical keyboard" — showing 3 of about 41,208 matches

1. Keychron K8 Pro Wireless Mechanical Keyboard - Brown Switches — $79.99
   total $79.99 · free shipping · New · was $99.00 (19% off)
   seller keeb_supply · 99.6% positive (8421 ratings) · top rated, ships from US
   Item v1|335894120043|0 · https://www.ebay.com/itm/335894120043

2. Ducky One 3 TKL Mechanical Keyboard RGB Hot-Swappable — $84.50
   total $92.45 · $7.95 shipping · New
   seller pc_parts_direct · 98.9% positive (3310 ratings) · accepts offers
   Item v1|326770118254|0 · https://www.ebay.com/itm/326770118254

What it does — and what it deliberately doesn't

Every tool is read-only. This server searches and reads listings. It cannot bid, add to a cart, place an order, or spend money. When you want to buy, it hands you a listing link and you check out yourself.

It's built on the official eBay Browse API — no scraping, no browser automation, no cookie replay. It won't break on a layout change and won't put you in breach of eBay's terms of use.

Tools

Two things worth knowing about search_ebay, because they're what eBay has and a fixed-price catalogue doesn't:

• buying_option filters to auction, buy_it_now, or accepts_offers.

• sort: "ending_soonest" — combined with buying_option: "auction", that's how you find auctions about to close.

Getting API keys

1. Sign in at developer.ebay.com/my/keys.

2. Create an application and open the Production keyset.

3. Copy the App ID (Client ID) and the Cert ID (Client Secret).

That's all. This server uses the OAuth client-credentials flow, so you do not need a user token, a redirect URI, or an "RuName".

New developer accounts may need to clear eBay's verification before the keys page opens up — that typically takes about a business day.

Install

git clone https://github.com/Kirat5690/shopping-mcp.git

cd shopping-mcp && npm install && npm run build

Connect it to a client

Claude Code

claude mcp add shopping --env EBAY_CLIENT_ID=your-app-id --env EBAY_CLIENT_SECRET=your-cert-id -- node /absolute/path/to/shopping-mcp/dist/index.js

Claude Desktop

Edit claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shopping": {
      "command": "node",
      "args": ["C:\\path\\to\\shopping-mcp\\dist\\index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your-app-id",
        "EBAY_CLIENT_SECRET": "your-cert-id",
        "EBAY_MARKETPLACE_ID": "EBAY_US"
      }
    }
  }
}

Restart the client, then ask it to run check_ebay_connection to confirm the credentials work.

Test your keys first (optional, but faster)

Registering a server and restarting a client is a slow way to discover a typo. To check credentials straight away:

EBAY_CLIENT_ID=your-app-id EBAY_CLIENT_SECRET=your-cert-id npm run check

On Windows PowerShell:

$env:EBAY_CLIENT_ID="your-app-id"; $env:EBAY_CLIENT_SECRET="your-cert-id"; npm run check

It prints the resolved configuration, makes one live call, and exits non-zero if anything is wrong. npm run check also reads a .env file if you have one, so cp .env.example .env, fill it in, and just run npm run check.

Configuration reference

Notes on the numbers

• Landed price is what gets ranked. Sorting by price uses item price plus shipping, so a cheap item with expensive postage doesn't win on a technicality. eBay's own price sort doesn't always do this.

• Some listings have no total. Where eBay reports shipping as calculated at checkout, there's no landed price until a delivery address is known, and the listing says so rather than guessing.

• No currency conversion. Prices are shown in the marketplace's own currency, exactly as eBay returns them.

• Listings are individual sales, not catalogue entries. Two results with near-identical titles can differ in condition, bundle contents, or region. Worth checking before treating them as the same item.

• find_deals only sees advertised discounts. It filters on eBay's strikethrough "was" price, so a genuinely cheap listing that never claimed a discount won't appear.

Development

npm test

The suite runs without any eBay credentials. It covers the money and landed-price logic, output formatting, and an end-to-end MCP protocol test that boots the server over stdio and exercises tool registration, schema validation, and the unconfigured-credential paths.

npm run watch      # recompile on change
npm run typecheck  # types only, no emit

Layout:

src/
  index.ts     server entry point and stdio wiring
  tools.ts     MCP tool definitions
  ebay.ts      Browse API client and OAuth token cache
  config.ts    environment parsing and marketplace table
  money.ts     price parsing, landed totals, ranking
  format.ts    human-readable output
  http.ts      fetch with timeout and retry

A note on scope

Earlier versions also supported Amazon through the Product Advertising API. That was removed in v0.2.0: PA-API requires an approved Amazon Associates account, and Amazon revokes access if the account makes no qualifying sales — too high a bar for most people to get the server running at all.

The Amazon client and its AWS SigV4 signing are preserved in git history at tag v0.1.0-amazon if you have an approved account and want them back.

Licence

MIT — see LICENSE.

Not affiliated with, endorsed by, or sponsored by eBay. Your use of the eBay API is governed by the eBay API License Agreement.