ebay-mcp

# ebay-mcp

> Local MCP server that exposes 313 tools covering 100% of the eBay Sell APIs to AI coding assistants (Claude, Cursor, Windsurf, and any MCP-compatible client). Runs entirely on your machine with no cloud relay.

Built with TypeScript/Node.js, the MCP SDK, Effect-backed validation with a Zod-compatible MCP adapter, and OpenAPI-generated eBay types. Supports OAuth 2.0, configurable tool exposure, MCP Apps read-only views, and the eBay Trading API (legacy XML).

## Getting Started

- [README](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md): Full setup guide, capability map, configuration reference, comparison table, available tools, safety scope, and usage examples
- [.env.example](https://github.com/YosefHayim/ebay-mcp/blob/main/.env.example): All supported environment variables with descriptions
- [Configuration Guide](https://github.com/YosefHayim/ebay-mcp/blob/main/docs/auth/CONFIGURATION.md): Every environment variable, OAuth step, and scope
- [OAuth Quick Reference](https://github.com/YosefHayim/ebay-mcp/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md): Scopes, troubleshooting, and examples
- [CHANGELOG.md](https://github.com/YosefHayim/ebay-mcp/blob/main/CHANGELOG.md): Full version history

## API Coverage

Tool definitions and handlers are co-located per family in `src/tools/categories/`:

- [Account](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/account.ts): Business, fulfillment, payment, and return policies; programs; subscriptions; sales tax
- [Inventory](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/inventory.ts): Inventory items, offers, locations, item groups, bulk operations, SKU/location mapping, local photo/video upload (Media API)
- [Fulfillment](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/fulfillment.ts): Orders, shipping, refunds, disputes, payment-dispute evidence
- [Marketing](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/marketing.ts): Promoted-listings campaigns, ads, promotions, bidding, reports
- [Analytics](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/analytics.ts): Seller standards, traffic reports, customer-service metrics
- [Communication](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/communication.ts): Buyer–seller messaging, negotiations, notifications, feedback
- [Taxonomy](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/taxonomy.ts): Category trees, item aspects, item conditions
- [Metadata](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/metadata.ts): Return policies, sales-tax jurisdictions, automotive compatibility
- [Other](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/other.ts): Identity, compliance, VeRO, translation, and international shipping support APIs
- [Developer](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/developer.ts): Rate limits, signing keys, client registration
- [Trading](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/trading.ts): Legacy XML API — fixed-price and auction listing management (create, revise, relist, end)
- [Token Management](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/tokenManagement.ts): OAuth token retrieval, refresh, and diagnostics
- [Connector](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/connector.ts): ChatGPT connector search/fetch tools over the eBay MCP catalogue

## Features and Runtime Behavior

- [README Capability Map](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#capability-map): Tool families, workflow examples, and `EBAY_MCP_TOOLS` family names
- [Tool Exposure Modes](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#tool-exposure-ebay_mcp_tools): `all`, `dynamic`, and family-list modes for controlling the advertised tool surface
- [Interactive UI / MCP Apps](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#interactive-ui-mcp-apps): Optional read-only table, card, chart, and stat views for capable hosts
- [Logging](https://github.com/YosefHayim/ebay-mcp/blob/main/docs/logging.md): Runtime logging rules, stderr behavior, and MCP-safe output guidance
- [Troubleshooting](https://github.com/YosefHayim/ebay-mcp/blob/main/docs/troubleshooting.md): Common setup, auth, client, and API failure modes

## Security & Compliance

- [SECURITY.md](https://github.com/YosefHayim/ebay-mcp/blob/main/SECURITY.md): Vulnerability reporting and security policy
- [EBAY_COMPLIANCE.md](https://github.com/YosefHayim/ebay-mcp/blob/main/EBAY_COMPLIANCE.md): eBay API terms compliance notes
- [CODE_OF_CONDUCT.md](https://github.com/YosefHayim/ebay-mcp/blob/main/CODE_OF_CONDUCT.md): Community standards

## Build and Contribution

- [CONTRIBUTING.md](https://github.com/YosefHayim/ebay-mcp/blob/main/CONTRIBUTING.md): How to add tools, run tests, and open PRs
- [CODE-STYLE.md](https://github.com/YosefHayim/ebay-mcp/blob/main/CODE-STYLE.md): TypeScript, Effect, schema, TSDoc, file naming, and endpoint implementation rules
- [ARCHITECTURE.md](https://github.com/YosefHayim/ebay-mcp/blob/main/ARCHITECTURE.md): Current module map and architecture overview
- [Current ADRs](https://github.com/YosefHayim/ebay-mcp/tree/main/docs/adr/current): Accepted decisions for formatter, CLI, dependency, CI, layout, and style backlog rules
- [AGENTS.md](https://github.com/YosefHayim/ebay-mcp/blob/main/AGENTS.md): Shared agent contract, validation commands, module ownership, and add-an-endpoint workflow
- [CLAUDE.md](https://github.com/YosefHayim/ebay-mcp/blob/main/CLAUDE.md): Claude Code entry point importing AGENTS.md
- [GitHub Copilot instructions](https://github.com/YosefHayim/ebay-mcp/blob/main/.github/copilot-instructions.md): Copilot-specific reminders that point back to AGENTS.md and CODE-STYLE.md

## Optional

- [API_STATUS.md](https://github.com/YosefHayim/ebay-mcp/blob/main/docs/API_STATUS.md): Live eBay API endpoint health snapshot (auto-updated weekly)
- [Sell Apps OpenAPI specs](https://github.com/YosefHayim/ebay-mcp/tree/main/docs/sell-apps): Checked-in eBay OpenAPI specs used by sync and type generation
- [Docker](https://github.com/YosefHayim/ebay-mcp/blob/main/Dockerfile): Container setup for running the server
- [Translated READMEs](https://github.com/YosefHayim/ebay-mcp#readme): Available in 简体中文, Español, Português (BR), 日本語, 한국어, Français, Deutsch, and Русский

## FAQ

### What is the eBay MCP server?

A local Model Context Protocol (MCP) server that exposes 313 tools covering 100% of eBay's Sell APIs (283 endpoints) to AI assistants such as Claude, Cursor, and Cline.

### Is this an official eBay product?

No. It is an unofficial, third-party open-source project and 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.

### How many eBay APIs and tools does it cover?

313 tools across 283 unique endpoints — 100% of eBay's Sell APIs.

### Is it free and open source?

Yes, under the MIT license.

### Does it run locally or in the cloud?

Entirely locally over STDIO or local HTTP. There is no cloud relay; eBay credentials never leave your machine.

### What do I need to get started?

Node.js >= 20, a free eBay Developer account (Client ID and Client Secret), then run `npm run setup`.

### What are the eBay API rate limits?

About 1,000 requests/day with client credentials, or 10,000–50,000 requests/day with a user token via OAuth, depending on 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, configurable tool exposure, generated eBay DTO types, and type-safe Effect-backed validation are built in.

### Can I expose only some tools?

Yes. `EBAY_MCP_TOOLS=all` exposes everything, `EBAY_MCP_TOOLS=dynamic` exposes discovery tools first, and a comma-separated family list exposes only those families.

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

Yes — listing create, revise, relist, and end operations for fixed-price listings (the default) and for auctions (`format: "AUCTION"` routes to `AddItem`, `ReviseItem`, `EndItem`, and `RelistItem`).

### 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, Effect-backed validation with a Zod-compatible MCP adapter, 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 runs on your machine; it still needs internet access and valid credentials to reach eBay's live APIs.