# ebay-mcp

> Local MCP server that exposes 379 tools covering 100% of the eBay Sell, Commerce and Developer APIs it tracks 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, Zod tool-input schemas, Effect for typed async errors, 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
- [Releases](https://github.com/YosefHayim/ebay-mcp/releases): Version history and release notes

## 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; rate tables, payout settings, combined shipping rules, and user preferences (Account API v2, [accountV2.ts](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/accountV2.ts))
- [Finances](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/finances.ts): Payouts, transactions, transfers, seller funds, billing activity, order earnings
- [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)
- [Feed](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/feed.ts): Order, inventory, and customer-service-metric feed tasks; schedules and templates; feed file upload/download
- [Stores](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/stores.ts): eBay Store details, store categories, category tasks
- [Fulfillment](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/fulfillment.ts): Orders, shipping, refunds, disputes, payment-dispute evidence
- [Logistics](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/logistics.ts): Shipping quotes, label purchase, shipments, label download (limited release)
- [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, expired categories, bulk aspect export, charitable organizations (Charity API, [charity.ts](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/charity.ts))
- [Metadata](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/metadata.ts): Return policies, sales-tax jurisdictions, automotive compatibility, shipping carriers/services/locations, handling times
- [Other](https://github.com/YosefHayim/ebay-mcp/blob/main/src/tools/categories/other.ts): Identity, 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 & Troubleshooting](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#logging--troubleshooting): stderr-only logging and the `npm run diagnose` starting point

## Security & Compliance

- [Scope and safety](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#scope-and-safety): What the server can change, and the compliance duties that stay with you

## Build and Contribution

- [Contributing](https://github.com/YosefHayim/ebay-mcp/blob/main/README.md#contributing): Validation commands and PR workflow

## Optional

- [Spec sources](https://github.com/YosefHayim/ebay-mcp/blob/main/src/scripts/specSources.ts): eBay OpenAPI spec URLs that `pnpm sync` downloads to generate types
- [Docker](https://github.com/YosefHayim/ebay-mcp/blob/main/Dockerfile): Container setup for running the server

## FAQ

### What is the eBay MCP server?

A local Model Context Protocol (MCP) server that exposes 379 tools covering 100% of the eBay Sell, Commerce and Developer APIs it tracks (356 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?

379 tools across 356 unique endpoints — 100% of the eBay Sell, Commerce and Developer APIs it tracks.

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

### 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 Zod 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, Zod schemas for tool inputs, Effect for typed async errors, 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.
