# shopping-mcp

An [MCP](https://modelcontextprotocol.io) 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

| Tool | What it's for |
| --- | --- |
| `search_ebay` | Keyword search with price, condition, buying-format, shipping, and location filters. |
| `get_listing_details` | Full record for one listing: item specifics, seller, returns, auction end time. |
| `find_deals` | Only listings discounted at least *N* % off their original price, cheapest first. |
| `check_ebay_connection` | Show the current config and make a live test call. **Run this first when something isn't working.** |

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](https://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

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

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

## Connect it to a client

### Claude Code

```bash
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`

```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:

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

On Windows PowerShell:

```bash
$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

| Variable | Required | Default | Notes |
| --- | --- | --- | --- |
| `EBAY_CLIENT_ID` | yes | — | App ID from the production keyset. |
| `EBAY_CLIENT_SECRET` | yes | — | Cert ID from the same keyset. |
| `EBAY_MARKETPLACE_ID` | no | `EBAY_US` | `EBAY_CA`, `EBAY_GB`, `EBAY_AU`, `EBAY_DE`, … |
| `EBAY_ENVIRONMENT` | no | `production` | Set to `sandbox` to use sandbox keys. |
| `EBAY_AFFILIATE_CAMPAIGN_ID` | no | — | Returns affiliate-tagged listing links. |
| `EBAY_DELIVERY_POSTAL_CODE` | no | — | Improves shipping-cost accuracy. |
| `EBAY_DELIVERY_COUNTRY` | no | — | ISO country code, e.g. `CA`. |
| `SHOPPING_MCP_TIMEOUT_MS` | no | `15000` | Per-request timeout. |

## 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

```bash
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.

```bash
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`](https://github.com/Kirat5690/shopping-mcp/releases/tag/v0.1.0-amazon) if you have an approved account and want them back.

## Licence

MIT — see [LICENSE](LICENSE).

Not affiliated with, endorsed by, or sponsored by eBay. Your use of the eBay API is governed by the [eBay API License Agreement](https://developer.ebay.com/join/api-license-agreement).