yosefhayim/ebay-mcp

The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay’s Sell APIs. 298 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 Developer — directly to eBay’s Sell APIs. It exposes 298 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
• Capability map
• eBay MCP vs. the raw eBay API
• One-click AI setup
• Quick start
• Demo
• Configuration
• Available tools
• Interactive UI (MCP Apps) — beta
• Usage examples
• Scope and safety
• Logging & troubleshooting
• FAQ
• Contributing
• Resources
• License
• Contributors

Features

• 298 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, Effect-backed tool input validation, 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 through GitHub Actions.

Capability map

Use this map when deciding which tool family to expose, or when asking an assistant what it can do. The family names match EBAY_MCP_TOOLS, so you can run with all tools, dynamic discovery, or only the families needed for a specific workflow.

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.

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. Verify with a read-only request

Restart your MCP client and ask:

“Check my eBay API rate limits.”

That should call ebay_get_rate_limits or ebay_get_user_rate_limits and confirms the server, credentials, and MCP client wiring without changing seller data.

5. Use

Start managing eBay through your AI assistant. Begin with read-only questions, then move to mutating inventory, order, or campaign tools after you have confirmed the target environment is sandbox or production.

Demo

See the eBay MCP Server in action with Claude Desktop:

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

Configuration

Available tools

Interactive UI (MCP Apps)

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.

Scope and safety

• Unofficial project. This is not an eBay product and does not grant any additional API rights beyond your own eBay Developer account.
• Local server, live APIs. The MCP server runs on your machine, but tools still call eBay’s sandbox or production APIs over the internet.
• Mutating tools can change seller data. Inventory, fulfillment, marketing, and Trading tools may create, revise, refund, end, or otherwise update eBay records. Test in sandbox first.
• Tool exposure is configurable. Use EBAY_MCP_TOOLS=dynamic or a family list when you want a smaller, workflow-specific tool surface.
• Interactive views are read-only. MCP Apps views can page, refresh, and drill into read tools, but they do not mutate eBay data.
• Compliance remains yours. Keep credentials secure, monitor rate limits, and follow eBay’s API terms and data-handling rules.

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

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.
• Code style lives in CODE-STYLE.md. Architecture and decision context live in ARCHITECTURE.md and ADRs.
• Full contribution guidelines: CONTRIBUTING.md.

Resources

Project docs:

• Configuration Guide — every environment variable, OAuth step, and eBay scope.
• OAuth Quick Reference — scopes, troubleshooting, and examples.
• Logging Guide and Troubleshooting Guide — operational help after setup.
• Architecture, CODE-STYLE.md, AGENTS.md, and llms.txt — contributor and agent entry points.
• CHANGELOG.md, SECURITY.md, CODE_OF_CONDUCT.md, and the Issue Tracker.

Official specs and tooling:

• eBay Developer Portal, Sell API docs, API License Agreement, Data Handling Requirements, and API Status.
• Model Context Protocol and the MCP Apps SDK.
• Node.js, npm package, TypeScript, Effect, Biome, Vitest, and GitHub Actions.
• AGENTS.md convention, Claude Code, GitHub Copilot repository instructions, and llms.txt.

License

MIT — see LICENSE.

Contributors

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

---