ebay-mcp

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, SECURITY.md, and EBAY_COMPLIANCE.md.

Table of contents

• Features

• eBay MCP vs. the raw eBay API

• One-click AI setup

• Quick start

• Demo

• Configuration

• Available tools

• Usage examples

• Logging & troubleshooting

• FAQ

• Contributing

• Resources

• License

• Contributors

Related MCP server: commercetools Commerce MCP

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.

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.

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.

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

Authentication & rate limits

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 and OAuth Quick Reference 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.

Available tools

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

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.

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.

• 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.

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

What is the eBay MCP server?

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

Is this an official eBay product?

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

Which AI assistants and MCP clients are supported?

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.

Can I use it with Claude, ChatGPT, or Cursor?

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.

How many eBay APIs and tools does it cover?

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

Is it free and open source?

Yes. It is released under the MIT license.

Does it run locally or in the cloud?

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

What do I need to get started?

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

What are the eBay API rate limits?

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.

Does it support both sandbox and production?

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

Are my credentials and data secure?

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

How is this different from calling the eBay API directly?

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

Does it support eBay's legacy Trading API (XML)?

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

How do I get higher rate limits?

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

What is it built with?

TypeScript and Node.js (ESM), using the official MCP SDK, Zod for validation, and OpenAPI-generated types.

How do I update to the latest version?

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

Does it work offline?

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.

Contributing

Contributions welcome. Fork → branch → add tests → npm run check && npm test → commit with Conventional Commits → open a PR.

• Working on the codebase or with a coding agent? Start with AGENTS.md — build/test commands, module map, and the add-an-endpoint workflow.

• Full guidelines: CONTRIBUTING.md.

Resources

• eBay Developer Portal — API docs and credentials

• eBay API License Agreement — terms and compliance

• eBay Data Handling Requirements — data protection and privacy

• MCP Documentation — Model Context Protocol spec

• OAuth Quick Reference — scopes, troubleshooting, examples

• eBay API Status — official status page (also via the ebay_get_api_status tool and the in-repo snapshot)

• CHANGELOG.md · SECURITY.md · CODE_OF_CONDUCT.md

• Issue Tracker — bug reports and feature requests

License

MIT — see LICENSE.

Contributors

Thanks to everyone who has helped make this project better! 🎉

Support this project · Created by Yosef Hayim Sabag

eBay MCP server · Model Context Protocol for eBay Sell APIs · connect Claude, Cursor, and any AI assistant to eBay inventory, orders, marketing, and analytics.