eBay MCP服务器

Listing preflight: required item specifics

Before calling ebay_create_or_replace_inventory_item, ebay_create_offer, or ebay_get_listing_fees, fetch the live requirements for the selected category:

ebay_get_default_category_tree_id → ebay_get_category_suggestions → ebay_get_item_aspects_for_category

The aspects response identifies required and recommended item specifics. Put every required aspect on the inventory item before creating its offer. Requirements vary by category and marketplace, so re-run the lookup when either changes; do not rely on examples or a fixed global fallback value.

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.

<details> <summary><strong>Click to copy the AI setup prompt</strong></summary>

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/

</details>

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.

HTTP deploy (optional — Docker / Railway / self-hosted):

Quick start

Usage examples

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

• Set up OAuth — "Help me set up OAuth for my eBay account." → generates an authorization URL via ebay_get_oauth_url, then configures the refresh token. Unlocks 10k–50k req/day.
• Manage inventory — "Show me all my active listings." → ebay_get_inventory_items returns SKUs, quantities, and status.
• Look up offers — ebay_get_offers returns offers for one required SKU. To enumerate offers across the inventory, call ebay_get_inventory_items first, then call ebay_get_offers once per SKU.
• Manage fulfillment policies — "Create a shipping policy, then update its handling time." → ebay_create_fulfillment_policy creates the reusable policy ID and ebay_update_fulfillment_policy replaces its settings.
• Process orders — "Get all unfulfilled orders from the last 7 days." → ebay_get_orders with date and fulfillment-status filters.
• Create campaigns — "Create a promoted-listing campaign for electronics." → ebay_create_campaign and related marketing tools.
• Bulk operations — "Apply a 10% discount to all 'Vintage Watches' items." → ebay_get_inventory_items + ebay_update_offer across matches.

Demo

See the eBay MCP Server in action with Claude Desktop:

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

Configuration

<details open> <summary><strong>Environment variables, tool exposure, auth &amp; client compatibility</strong></summary>

📖 Full reference — every environment variable, OAuth step, and scope — is in the Configuration Guide. 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_SITE_ID=0 # Trading API site override; defaults from EBAY_MARKETPLACE_ID

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) EBAY_READ_ONLY=false # when true, only register read-only tools (gets/lists/searches)

eBay MCP vs. the raw eBay API

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

Logging & troubleshooting

• Logging — Winston-based, written to stderr (MCP-safe) with optional file output. See docs/logging.md.
• Troubleshooting — server not appearing, auth errors, rate limits, empty results. Start with npm run diagnose, then see docs/troubleshooting.md.

FAQ

<details> <summary><strong>What is the eBay MCP server?</strong></summary>

A local Model Context Protocol server that exposes 299 tools covering 100% of eBay's Sell APIs (270 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.

</details>

<details> <summary><strong>Is this an official eBay product?</strong></summary>

No. This is an unofficial, third-party open-source project. It is not affiliated with, authorized, or endorsed by eBay Inc.

</details>

<details> <summary><strong>Which AI assistants and MCP clients are supported?</strong></summary>

Nine clients are auto-configured by npm run setup: Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer. Any MCP-compatible client can connect.

</details>

<details> <summary><strong>Can I use it with Claude, ChatGPT, or Cursor?</strong></summary>

Yes. It works with Claude Desktop and Claude Code out of the box, with Cursor and other MCP-enabled IDEs, and with any assistant that supports the Model Context Protocol. The one-click setup prompt above works with ChatGPT and other assistants too.

</details>

<details> <summary><strong>Why don't I see the interactive tables and charts?</strong></summary>

Interactive MCP Apps views only appear on hosts that announce the capability (e.g. Claude); other clients get the same data as plain JSON. Also confirm you have not set EBAY_MCP_UI=off and that the views are built (npm run build runs build:ui).

</details>

<details> <summary><strong>How many eBay APIs and tools does it cover?</strong></summary>

299 tools across 270 unique endpoints — 100% of eBay's Sell APIs.

</details>

<details> <summary><strong>Is it free and open source?</strong></summary>

Yes. It is released under the MIT license.

</details>

<details> <summary><strong>Does it run locally or in the cloud?</strong></summary>

It runs entirely on your machine over STDIO (or local HTTP). There is no cloud relay — your eBay credentials never leave your computer.

</details>

<details> <summary><strong>What do I need to get started?</strong></summary>

Node.js ≥ 20, a free eBay Developer Account (Client ID + Client Secret), then run npm run setup.

</details>

<details> <summary><strong>What are the eBay API rate limits?</strong></summary>

Client credentials (the default) allow about 1,000 requests/day. Authenticating with a user token via OAuth raises this to 10,000–50,000 requests/day depending on your account tier.

</details>

<details> <summary><strong>Does it support both sandbox and production?</strong></summary>

Yes. Switch with the EBAY_ENVIRONMENT variable (sandbox or production).

</details>

<details> <summary><strong>Are my credentials and data secure?</strong></summary>

Credentials are stored locally in your .env file and used only to call eBay directly. See SECURITY.md and EBAY_COMPLIANCE.md.

</details>

<details> <summary><strong>How is this different from calling the eBay API directly?</strong></summary>

You interact in natural language through your AI assistant. OAuth token management, automatic retries with backoff, and type-safe Effect-backed validation are built in. See the comparison table above.

</details>

<details> <summary><strong>Does it support eBay's legacy Trading API (XML)?</strong></summary>

Yes. Fixed-price listing create, revise, relist, and end operations are supported through the Trading API tools.

</details>

<details> <summary><strong>How do I get higher rate limits?</strong></summary>

Complete the OAuth flow with npm run setup to authenticate with a user token (10k–50k requests/day instead of the default 1k).

</details>

<details> <summary><strong>What is it built with?</strong></summary>

TypeScript and Node.js (ESM), using the official MCP SDK, Effect-backed validation with a Zod-compatible MCP adapter, and OpenAPI-generated types.

</details>

<details> <summary><strong>How do I update to the latest version?</strong></summary>

Run npm install -g ebay-mcp@latest (or npm update -g ebay-mcp).

</details>

<details> <summary><strong>Does it work offline?</strong></summary>

No. "Runs locally" means the server process runs on your machine — it still needs an internet connection and valid credentials to reach eBay's live APIs.

</details>