# Ebay Mcp > Open source local MCP server providing AI assistants with comprehensive access to eBay's Sell APIs. Includes 325 tools for inventory management, order fulfillment, marketing campaigns, analytics, developer tools, and more. - **Type:** MCP server - **Install:** `agentstack add mcp-yosefhayim-ebay-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [YosefHayim](https://agentstack.voostack.com/s/yosefhayim) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [YosefHayim](https://github.com/YosefHayim) - **Source:** https://github.com/YosefHayim/ebay-mcp - **Website:** https://www.npmjs.com/package/ebay-mcp ## Install ```sh agentstack add mcp-yosefhayim-ebay-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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](https://modelcontextprotocol.io) 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](https://developer.ebay.com/join/api-license-agreement) and [data-handling requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html), keeping your credentials secure, and staying within rate limits. Test in sandbox before production. See [LICENSE](LICENSE), [SECURITY.md](SECURITY.md), and [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.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](https://developer.ebay.com/). 2. Generate application keys in the [Developer Portal](https://developer.ebay.com/my/keys). 3. Save your **Client ID** and **Client Secret**. ### 2. Install ```bash npm install -g ebay-mcp # from npm (recommended) ``` Or from source: ```bash git clone https://github.com/YosefHayim/ebay-mcp.git cd ebay-mcp && npm install && npm run build ``` ### 3. Run the setup wizard ```bash 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](https://developer.ebay.com/my/keys), 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. ```bash 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/OAUTH_QUICK_REFERENCE.md) for details, and monitor usage in the [Developer Portal](https://developer.ebay.com/my/api_usage). ### 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](https://modelcontextprotocol.io), 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`)](https://github.com/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](https://github.com/YosefHayim) - **Source:** [YosefHayim/ebay-mcp](https://github.com/YosefHayim/ebay-mcp) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/ebay-mcp 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-yosefhayim-ebay-mcp - Seller: https://agentstack.voostack.com/s/yosefhayim - 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%.