# Ebay Browse Mcp

> Minimal MCP server for searching eBay listings via the Browse API. Works with any MCP-compatible host: Claude Desktop, Cursor, VS Code Copilot, Cline, Continue, Zed, Windsurf, LM Studio, Goose.

- **Type:** MCP server
- **Install:** `agentstack add mcp-capitansuat-ebay-browse-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [capitansuat](https://agentstack.voostack.com/s/capitansuat)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [capitansuat](https://github.com/capitansuat)
- **Source:** https://github.com/capitansuat/ebay-browse-mcp

## Install

```sh
agentstack add mcp-capitansuat-ebay-browse-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ebay-browse-mcp

[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://developer.ebay.com/api-docs/buy/browse/overview.html)

Minimal MCP server for searching eBay listings via the [Browse API](https://developer.ebay.com/api-docs/buy/browse/overview.html). Communicates over stdio JSON-RPC, so it works with any MCP-compatible host (Claude Desktop, Claude Code, Cursor, VS Code Copilot, Cline, Continue, Zed, Windsurf, LM Studio, Goose, and others).

## Features

- Two tools: `search_ebay` (keyword, filters, sort, pagination) and `get_item_details` (full item record by ID)
- OAuth 2.0 client credentials flow, token cached in memory
- Sandbox or production via a single env var
- Pure Python, no framework lock-in beyond the official MCP SDK

## Install

```bash
git clone https://github.com//ebay-browse-mcp.git
cd ebay-browse-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

## Configure

1. Create an eBay developer account at https://developer.ebay.com
2. Generate an Application Keyset (both sandbox and production keysets are available)
3. Enable OAuth for the keyset on the eBay developer portal
4. Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
nano .env
```

```
EBAY_CLIENT_ID=your_app_id_here
EBAY_CLIENT_SECRET=your_cert_id_here
EBAY_MARKETPLACE=EBAY_GB
EBAY_ENV=sandbox
```

### Sandbox vs production

- **`EBAY_ENV=sandbox`** routes requests to `api.sandbox.ebay.com`. Sandbox listings are synthetic test data, not real inventory. Start here to verify your OAuth flow and integration end-to-end with no approval friction.
- **`EBAY_ENV=production`** routes to `api.ebay.com` and returns real eBay listings. To use production you must:
  1. Use the production keyset credentials (different `CLIENT_ID` and `CLIENT_SECRET` than sandbox)
  2. Comply with eBay's [marketplace account deletion notification](https://developer.ebay.com/marketplace-account-deletion) process, or apply for an exemption if you do not store eBay user data
  3. Enable OAuth on the production keyset

Switching environments is a one-line change to `.env`. The credentials for each environment are separate and not interchangeable.

## Test the client directly

```bash
.venv/bin/python ebay_client.py "macbook pro m4 max 64gb"
```

Expected output: a list of items with title, price, and URL.

## Register with your MCP host

The server speaks stdio JSON-RPC. Add it to your host's MCP configuration with two values:

- **command**: absolute path to the venv Python (`/absolute/path/to/ebay-browse-mcp/.venv/bin/python`)
- **args**: `["/absolute/path/to/ebay-browse-mcp/server.py"]`

### Claude Desktop / Claude Code / Cursor / Windsurf / LM Studio / Cherry Studio / Goose

These hosts share the `mcpServers` JSON shape. Add the block below to the relevant config file and restart the host.

```json
{
  "mcpServers": {
    "ebay-browse": {
      "command": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/ebay-browse-mcp/server.py"
      ]
    }
  }
}
```

Config file locations:

| Host | Path |
| --- | --- |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor (global) | `~/.cursor/mcp.json` |
| Cursor (per project) | `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Claude Code | `claude mcp add ebay-browse /absolute/path/to/.venv/bin/python /absolute/path/to/server.py` (CLI) |

### VS Code Copilot

VS Code uses `servers` (not `mcpServers`) under the `mcp` section of `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "ebay-browse": {
        "command": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/ebay-browse-mcp/server.py"]
      }
    }
  }
}
```

### Zed

Zed uses `context_servers` in `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "ebay-browse": {
      "command": {
        "path": "/absolute/path/to/ebay-browse-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/ebay-browse-mcp/server.py"]
      }
    }
  }
}
```

### Continue, Cline and others

Continue (`~/.continue/config.json`) uses an `mcpServers` array; Cline uses `cline_mcp_settings.json` with the same shape as Claude Desktop. Check your host's documentation for the exact file path. The command and args are always the same.

Once registered, restart the host and the `search_ebay` and `get_item_details` tools become available.

## Tool: `search_ebay`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search keyword, e.g. `"macbook pro m4 max 64gb"` |
| `limit` | integer | no (default 10) | Number of results, 1-200 |
| `filter_expr` | string | no | Browse API filter syntax, see below |
| `sort` | string | no | `price`, `-price`, `newlyListed`, `endingSoonest` |

Returns a list of items. Each item includes an `item_id` field (format `v1||0`) that can be passed to `get_item_details` for the full record.

### Filter examples

| Goal | `filter_expr` |
| --- | --- |
| Price range in GBP | `price:[100..500],priceCurrency:GBP` |
| New condition only | `conditions:{NEW}` |
| Buy It Now only | `buyingOptions:{FIXED_PRICE}` |
| UK sellers only | `itemLocationCountry:GB` |

Combine with commas: `price:[800..3500],priceCurrency:GBP,itemLocationCountry:GB`.

Full reference: https://developer.ebay.com/api-docs/buy/static/ref-buy-browse-filters.html

## Tool: `get_item_details`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `item_id` | string | yes | REST item ID from `search_ebay`, format `v1||0` |
| `fieldgroups` | string | no | `COMPACT` (price/availability only), `PRODUCT` (default plus product catalogue), or omit for full details |

Returns the full item record: title, description, item specifics (aspects), all images, condition, brand, MPN, category path, buying options, availability, seller details, item location, shipping options with estimated delivery dates, and return terms.

Typical chain: an LLM calls `search_ebay` to find candidates, then `get_item_details` on the promising ones to read full descriptions or shipping costs before recommending.

## Project structure

```
ebay-browse-mcp/
├── .env.example         template; copy to .env
├── .gitignore
├── README.md
├── requirements.txt
├── evaluation.xml       10 read-only LLM eval questions
├── ebay_client.py       Browse API client (no MCP dependency)
└── server.py            FastMCP server, wraps ebay_client.search_items
```

## Evaluation

`evaluation.xml` contains 10 read-only questions designed for LLM evaluation harnesses. Questions target stable response properties (shape, field values, filter behaviour) rather than specific listings, because eBay inventory changes constantly. Each question has a single verifiable string answer.

## Comparison with similar projects

Three open-source eBay MCP servers exist as of mid-2026. They target different use cases. Pick the one that fits yours:

| | **ebay-browse-mcp** (this) | [YosefHayim/ebay-mcp](https://github.com/YosefHayim/ebay-mcp) | [CooKey-Monster/EbayMcpServer](https://github.com/CooKey-Monster/EbayMcpServer) |
| --- | --- | --- | --- |
| **Best for** | Buyers: searching public listings | Sellers: managing inventory, orders, ads | Minimal auction listing |
| **eBay API** | Browse API (buyer-side) | Sell APIs (seller-side) | Browse API, single endpoint |
| **Tools** | 2 (`search_ebay`, `get_item_details`) with filters, sort, pagination | 325 tools, 100% Sell API coverage | 1 (`list_auction`) |
| **Language** | Python | TypeScript / Node 18+ | Python (uv) |
| **Setup** | venv + pip + `.env` | `npm install -g ebay-mcp` + interactive wizard | `uv pip install` |
| **Auth** | Client credentials | Client credentials + user OAuth (refresh tokens, 10k-50k req/day) | Client credentials |
| **Active maintenance** | Yes | Yes (frequent releases) | No (2 commits, stale) |
| **Footprint** | ~190 lines of code | 30+ files, src/api + src/tools + src/auth + scripts | ~5 files |

**Pick `ebay-browse-mcp` (this project) if:** you want an LLM to search eBay listings with filters (price range, condition, location, sort), with minimal setup and a small surface area. The goal is a focused tool that does one thing well.

**Pick YosefHayim/ebay-mcp if:** you run an eBay store and want an LLM to manage your inventory, fulfil orders, run marketing campaigns, or pull analytics. It is the most complete Sell-API integration available.

**Pick CooKey-Monster/EbayMcpServer if:** you want the absolute minimum dependency footprint and only need a single keyword lookup. Note that the repo has not been updated for over a year as of mid-2026.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [capitansuat](https://github.com/capitansuat)
- **Source:** [capitansuat/ebay-browse-mcp](https://github.com/capitansuat/ebay-browse-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-capitansuat-ebay-browse-mcp
- Seller: https://agentstack.voostack.com/s/capitansuat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.