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

📖 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
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)

By default all tools are advertised to the agent at once. On a long conversation that catalogue is a meaningful slice of the context window, so two opt-in modes let you shrink it:

The family list is literal — you get exactly what you name. ChatGPT connectors need the connector family (its search/fetch tools); add it explicitly, e.g. EBAY_MCP_TOOLS=connector,inventory. An unknown family name fails fast at startup with the valid list. Valid families: connector, token-management, account, inventory, fulfillment, marketing, analytics, metadata, taxonomy, communication, other, developer, trading.

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.

Auto-configured by npm run setup. Requires Node.js ≥ 20 and MCP protocol 1.0+ over STDIO (default) or HTTP.

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.

Beta — this feature is new and evolving alongside the MCP Apps spec, and host support is still rolling out. It is opt-in and falls back to plain JSON, so it never breaks existing clients. Toggle it with EBAY_MCP_UI (see Configuration).

On hosts that support MCP Apps, common read tools render their results as interactive views instead of raw JSON — a sortable table, a detail card, a chart, or a stat grid — using the host's own theme. Everywhere else, the exact same tools return plain JSON, so nothing breaks. It is built on the official MCP Apps SDK (@modelcontextprotocol/ext-apps), the extension that lets MCP servers ship interactive UI to conversational clients.

• Opt-in and host-gated. Views are advertised only to clients that announce the MCP Apps capability (e.g. Claude). Hosts without it (e.g. Cursor) silently get JSON.
• Kill-switch. Set EBAY_MCP_UI=off to force plain JSON everywhere, even on capable hosts.
• Token-cheap. Each view's HTML is fetched once by the host out of band (never into the model's context); the model only ever sees a one-line summary plus the structured data it would have received anyway.
• Read-only. Views only ever trigger read tools (drill into a row, page, refresh) — they never mutate your eBay data.

15 core-workflow tools opt in today, across four archetypes:

The views build into self-contained HTML with npm run build (or npm run build:ui); they ship in the published package and load with no network access of their own.

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.

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

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.

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.

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

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

Yes. It is released under the MIT license.

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

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

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.

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

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

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.

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

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

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

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

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.