Ebay Mcp

The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay's Sell APIs. 322 tools for inventory, orders, marketing, and analytics, running locally with your own keys.

Unofficial, open-source project — not affiliated with, authorized, or endorsed by eBay Inc.

English · 简体中文 · Español · Português (BR) · 日本語 · 한국어 · Français · Deutsch · Русский

---

eBay MCP is a local Model Context Protocol server that connects AI assistants — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code, and Amazon Q — directly to eBay's Sell APIs. It exposes 322 tools spanning 100% of eBay's Sell API surface (270 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — no cloud relay, and your eBay credentials never leave your computer.

> Disclaimer: Unofficial, third-party project — not affiliated with or endorsed by eBay Inc. Provided "as is" without warranty. You are responsible for complying with eBay's API License Agreement and data-handling requirements, keeping your credentials secure, and staying within rate limits. Test in sandbox before production. See [LICENSE](LICENSE), [SECURITY.md](SECURITY.md), and [EBAYCOMPLIANCE.md](EBAYCOMPLIANCE.md).

Table of contents

• [Features](#features)
• [eBay MCP vs. the raw eBay API](#ebay-mcp-vs-the-raw-ebay-api)
• [One-click AI setup](#one-click-ai-setup)
• [Quick start](#quick-start)
• [Demo](#demo)
• [Configuration](#configuration)
• [Available tools](#available-tools)
• [Interactive UI (MCP Apps) — beta](#interactive-ui-mcp-apps)
• [Usage examples](#usage-examples)
• [Logging & troubleshooting](#logging--troubleshooting)
• [FAQ](#faq)
• [Contributing](#contributing)
• [Resources](#resources)
• [License](#license)
• [Contributors](#contributors)

Features

• 322 eBay API tools — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
• 9 AI clients, auto-configured — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer.
• OAuth 2.0 built in — full user-token management with automatic refresh, and smart fallback from user tokens (10k–50k req/day) to client credentials (1k req/day).
• Resilient by default — automatic retry with exponential backoff on 429 rate limits, and consistent, loud error surfacing.
• Type-safe — TypeScript end to end, Zod-validated tool inputs, and OpenAPI-generated types.
• Local-first & private — runs over STDIO or local HTTP; your credentials and data never leave your machine.
• Sandbox and production — switch environments with a single variable.
• One-command setup — npm run setup configures credentials, OAuth, and your MCP client, with a browser auto-opened for the OAuth flow.
• Well tested — 1,000+ automated tests run in CI on every change.

eBay MCP vs. the raw eBay API

Both talk to the same eBay endpoints — the difference is everything you'd otherwise build yourself.

| | eBay MCP Server | Raw eBay REST API | | --- | --- | --- | | Interface | Natural language through your AI assistant | Hand-written HTTP requests and JSON parsing | | OAuth & token refresh | Built in, with automatic refresh | You implement and maintain it | | Rate-limit handling | Automatic retry with exponential backoff | Manual 429 handling and backoff | | Input validation | Zod schemas + TypeScript types on every tool | None — you validate your own payloads | | Setup | One wizard (npm run setup) | Per-call auth, headers, and marketplace wiring | | AI client support | 9 clients auto-configured | Not applicable | | API coverage | 322 tools across 100% of the Sell APIs, ready to call | Build each request from the docs | | Hosting | Runs locally, no cloud relay | Your own infrastructure |

One-click AI setup

> Let your AI assistant set this up for you. Copy the prompt below and paste it into Claude, ChatGPT, or any AI assistant with MCP support.

Click to copy the AI setup prompt

I want to set up the eBay MCP Server for my AI assistant. Please help me:

1. Install the eBay MCP server:
   npm install -g ebay-mcp

2. I need to configure it for [Claude Desktop / Cursor / Cline / Zed / Continue.dev / Windsurf / Claude Code CLI / Amazon Q] (choose one)

3. My eBay credentials are:
   - Client ID: [YOUR_CLIENT_ID]
   - Client Secret: [YOUR_CLIENT_SECRET]
   - Environment: [sandbox / production]
   - Redirect URI (RuName): [YOUR_REDIRECT_URI]

Please:
- Create the appropriate config file for my MCP client
- Set up the environment variables
- Help me complete the OAuth flow to get a refresh token for higher rate limits
- Test that the connection works

If I don't have eBay credentials yet, guide me through creating a developer account at https://developer.ebay.com/

Quick start

1. Get eBay credentials

1. Create a free eBay Developer Account.
2. Generate application keys in the Developer Portal.
3. Save your Client ID and Client Secret.

2. Install

npm install -g ebay-mcp            # from npm (recommended)

Or from source:

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp && npm install && npm run build

3. Run the setup wizard

npm run setup

The wizard configures your eBay credentials, sets up OAuth (for higher rate limits), auto-detects and configures your MCP client, and saves everything automatically.

4. Use

Restart your MCP client (Claude Desktop, etc.) and start managing eBay through your AI assistant.

📸 Visual setup walkthrough (eBay Developer Portal)

The setup wizard (npm run setup) handles OAuth automatically. Here's where to find your credentials in the eBay Developer Portal:

Step 1 — In the Developer Portal, copy your App ID (Client ID) and Cert ID (Client Secret):

Step 2 — In your app's User Tokens settings, copy the RuName (eBay Redirect URL):

Step 3 — Run npm run setup. It opens your browser for OAuth login and guides you through eBay sign-in:

Step 4 — Paste the authorization code from the callback URL when prompted:

The wizard exchanges the code for tokens, saves them, and configures your MCP client. You now have user-token authentication (10k–50k requests/day instead of the default 1k/day).

Demo

See the eBay MCP Server in action with Claude Desktop:

https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b

Configuration

> 📖 Full reference — every environment variable, OAuth step, and scope — is in the [Configuration Guide](docs/auth/CONFIGURATION.md). npm run setup writes the .env for you; the variables below are for reference.

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox            # or "production"
EBAY_REDIRECT_URI=your_runame
EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
EBAY_CONTENT_LANGUAGE=en-US         # default request content language
EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)

Tool exposure (EBAY_MCP_TOOLS)

By default all tools are advertised to the agent at once. On a long conversation that catalogue is a meaningful slice of the context window, so two opt-in modes let you shrink it:

| Value | Behavior | Works on | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | all (default, or unset) | Every tool advertised at startup. | every host | | dynamic | Only three discovery tools are visible (list_ebay_tools, enable_ebay_tools, disable_ebay_tools). The agent searches the catalogue and loads only the tools it needs; they then appear natively. | hosts that honor tools/listChanged (e.g. Claude) | | inventory,fulfillment,… | Registers only the named families (listed below), frozen for the session. | every host (incl. ChatGPT, Cursor) |

The family list is literal — you get exactly what you name. ChatGPT connectors need the connector family (its search/fetch tools); add it explicitly, e.g. EBAY_MCP_TOOLS=connector,inventory. An unknown family name fails fast at startup with the valid list. Valid families: connector, token-management, account, inventory, fulfillment, marketing, analytics, metadata, taxonomy, communication, other, developer, trading.

Authentication & rate limits

| Mode | Daily limit | Best for | Setup | | -------------------------------- | --------------- | ----------------------- | --------------------------------- | | Client credentials (default) | 1,000 req/day | Development, testing | Automatic with Client ID + Secret | | User token (recommended) | 10k–50k req/day | Production, high volume | OAuth via npm run setup |

User-token limits vary by account tier (Individual 10k · Commercial 25k · Enterprise 50k+). On a 429, the server retries with exponential backoff and surfaces the error. See the [Configuration Guide](docs/auth/CONFIGURATION.md) and [OAuth Quick Reference](docs/auth/OAUTHQUICKREFERENCE.md) for details, and monitor usage in the Developer Portal.

MCP client compatibility

Auto-configured by npm run setup. Requires Node.js ≥ 18 and MCP protocol 1.0+ over STDIO (default) or HTTP.

| Client | Platform | Config path | | ---------------------- | --------------------- | ---------------------------------------------------------------------------- | | Claude Desktop | macOS, Windows, Linux | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor IDE | macOS, Windows, Linux | ~/.cursor/mcp.json | | Zed Editor | macOS, Windows, Linux | ~/.config/zed/settings.json | | Cline | VS Code extension | ~/...globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | | Continue.dev | VS Code, JetBrains | ~/.continue/config.json | | Windsurf (Codeium) | macOS, Windows, Linux | ~/.codeium/windsurf/mcp_config.json | | Roo Code | VS Code extension | ~/...globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json | | Claude Code CLI | Terminal | ~/.claude.json | | Amazon Q Developer | AWS | ~/.aws/amazonq/mcp.json |

Available tools

322 tools, 100% Sell API coverage, organized by category. Each link points to the tool definitions and handlers in [src/tools/categories/](src/tools/categories/):

| Category | What you can do | | --- | --- | | [Account](src/tools/categories/account.ts) | Business, fulfillment, payment, and return policies; programs; subscriptions; sales tax | | [Inventory](src/tools/categories/inventory.ts) | Inventory items, offers, locations, item groups, bulk operations, SKU/location mapping | | [Fulfillment](src/tools/categories/fulfillment.ts) | Orders, shipping, refunds, disputes, payment-dispute evidence | | [Marketing](src/tools/categories/marketing.ts) | Promoted-listings campaigns, ads, promotions, bidding, bulk operations | | [Analytics](src/tools/categories/analytics.ts) | Traffic reports, seller standards, customer-service metrics | | [Communication](src/tools/categories/communication.ts) | Buyer–seller messaging, negotiations, notifications, feedback | | [Metadata](src/tools/categories/metadata.ts) | Return policies, sales-tax jurisdictions, automotive compatibility | | [Taxonomy](src/tools/categories/taxonomy.ts) | Category trees, item aspects, item conditions | | [Trading (legacy XML)](src/tools/categories/trading.ts) | Fixed-price listing create, revise, relist, end | | [Developer](src/tools/categories/developer.ts) | Rate limits, signing keys, client registration | | [Token Management](src/tools/categories/token-management.ts) | OAuth URL generation and token management |

Example tools: ebay_get_inventory_items, ebay_get_orders, ebay_create_offer, ebay_get_campaigns, ebay_get_oauth_url.

For the complete machine-readable index, see [llms.txt](llms.txt).

Interactive UI (MCP Apps)

> Beta — this feature is new and evolving alongside the MCP Apps spec, and host support is still rolling out. It is opt-in and falls back to plain JSON, so it never breaks existing clients. Toggle it with EBAY_MCP_UI (see [Configuration](#configuration)).

On hosts that support MCP Apps, common read tools render their results as interactive views instead of raw JSON — a sortable table, a detail card, or a chart — using the host's own theme. Everywhere else, the exact same tools return plain JSON, so nothing breaks. It is built on the official MCP Apps SDK (@modelcontextprotocol/ext-apps), the extension that lets MCP servers ship interactive UI to conversational clients.

• Opt-in and host-gated. Views are advertised only to clients that announce the MCP Apps capability (e.g. Claude). Hosts without it (e.g. Cursor) silently get JSON.
• Kill-switch. Set EBAY_MCP_UI=off to force plain JSON everywhere, even on capable hosts.
• Token-cheap. Each view's HTML is fetched once by the host out of band (never into the model's context); the model only ever sees a one-line summary plus the structured data it would have received anyway.
• Read-only. Views only ever trigger read tools (drill into a row, page, refresh) — they never mutate your eBay data.

13 core-workflow tools opt in today, across three archetypes:

| Archetype | Tools | | --- | --- | | Table | ebay_get_orders, ebay_get_shipping_fulfillments, ebay_get_offers, ebay_get_inventory_items, ebay_get_inventory_locations, ebay_get_payment_dispute_summaries | | Card | ebay_get_order, ebay_get_offer, ebay_get_inventory_item, ebay_get_payment_dispute, ebay_get_seller_standards_profile | | Chart | ebay_get_traffic_report, ebay_get_customer_service_metric |

The views build into self-contained HTML with npm run build (or npm run build:ui); they ship in the published package and load with no network access of their own.

Usage examples

Common tasks, phrased as you'd ask your AI assistant:

• *

…

Source & license

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

• Author: YosefHayim
• Source: YosefHayim/ebay-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/ebay-mcp

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