Repository avatar
Other Tools
v2.0.11
active

ebay-mcp

io.github.YosefHayim/ebay-mcp

Community MCP server for the eBay Sell, Commerce and Developer APIs (379 tools).

Documentation

eBay MCP server: connect Claude, Cursor and other AI assistants to eBay's Sell APIs

A local MCP server that gives AI assistants 379 tools for the eBay Sell, Commerce and Developer APIs, running with your own keys.

Unofficial open-source project. Not affiliated with, authorized or endorsed by eBay Inc.

npm version npm downloads per month CI status MIT license 379 eBay API tools

Website · npm · Releases

What it does

  • Connects Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code and Amazon Q Developer to eBay. Any MCP client can connect.
  • Covers inventory, orders, fulfillment, finances, feeds, stores, shipping labels, promoted listings, analytics, taxonomy, messaging and the legacy Trading API.
  • Handles OAuth 2.0 with automatic token refresh, and retries 429 rate limits with backoff.
  • Validates every tool input with Zod and uploads local photos and videos through the Media API.
  • Runs on your machine over STDIO or HTTP. There is no cloud relay and your credentials stay local.
  • Works with the eBay sandbox and production. One variable switches between them.

Quick start

1. Get eBay keys

Create a free eBay Developer Account. In the Developer Portal, copy the App ID (Client ID) and Cert ID (Client Secret).

Step 1: copy the Client ID and Client Secret from the eBay Developer Portal

In your app's User Tokens settings, copy the RuName (the eBay redirect URL).

Step 2: copy the RuName redirect URL

2. Run the setup wizard

Needs Node.js 24 or newer.

npm install -g ebay-mcp
npx ebay-mcp setup        # or: npm run setup, from a source checkout

The wizard saves your credentials, opens the browser for eBay sign-in and configures your MCP client.

Step 3: sign in to eBay during the OAuth flow

Paste the authorization code from the callback URL when it asks.

Step 4: paste the authorization code into the setup wizard

Watch the video tutorial for the full flow.

3. Verify with a read-only request

Restart your MCP client and ask: "Check my eBay API rate limits." This calls ebay_get_rate_limits and proves the server, credentials and client wiring work without changing seller data.

4. Use it

Start with read-only questions. Move to tools that change data only after you confirm whether you are on sandbox or production.

To add the server by hand, use the Claude Code one-liner:

claude mcp add ebay --env EBAY_CLIENT_ID=your_client_id --env EBAY_CLIENT_SECRET=your_client_secret --env EBAY_ENVIRONMENT=sandbox -- npx -y ebay-mcp

Or add this to any MCP client config:

{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_REDIRECT_URI": "your_runame",
        "EBAY_USER_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Configuration

The setup wizard writes the variables for you. See .env.example for the full list.

VariableDefaultWhat it does
EBAY_CLIENT_ID, EBAY_CLIENT_SECRETnoneYour eBay app keys.
EBAY_ENVIRONMENTsandboxsandbox or production.
EBAY_REDIRECT_URInoneThe RuName used for OAuth sign-in.
EBAY_USER_REFRESH_TOKENnoneUser token for higher rate limits.
EBAY_OAUTH_SCOPESdefault scopesReplaces the requested scope list. Keep the scopes you need.
EBAY_MARKETPLACE_IDEBAY_USDefault marketplace, overridable per tool.
EBAY_SITE_IDfrom marketplaceTrading API site override.
EBAY_CONTENT_LANGUAGEen-USDefault request content language.
EBAY_MCP_TOOLSallWhich tools are advertised. See below.
EBAY_READ_ONLYfalseWhen true, only read-only tools are registered.
EBAY_MCP_UIonoff forces plain JSON instead of interactive views.
EBAY_MCP_MEDIA_DIRS, EBAY_MCP_MEDIA_ROOTnoneDirectories the media and feed upload tools may read. Off until set.
EBAY_SIGNING_KEY_JWE, EBAY_SIGNING_PRIVATE_KEYnoneDigital Signatures for EU and UK sellers. Both come from ebay_create_signing_key.
MCP_PORT, MCP_HOST, MCP_AUTH_TOKEN, MCP_CORS_ORIGINSnoneHTTP mode settings. See Run over HTTP.

Tool exposure

A full catalogue takes a lot of context window. EBAY_MCP_TOOLS shrinks it:

ValueBehavior
all (default)Every tool is advertised at startup.
dynamicThree discovery tools (list_ebay_tools, enable_ebay_tools, disable_ebay_tools). The agent loads only the tools it needs. Needs a host that supports tools/listChanged, such as Claude.
inventory,fulfillmentOnly the named families, fixed for the session. Works on every host.

The family list is literal. ChatGPT connectors need the connector family, for example EBAY_MCP_TOOLS=connector,inventory. An unknown family name fails at startup and prints the valid names.

Read-only mode

Set EBAY_READ_ONLY=true to register only tools that read data (gets, lists, searches). Use it for first runs and for reporting assistants.

Authentication and rate limits

ModeDaily limitSetup
Client credentials (default)1,000 requestsAutomatic with Client ID and Secret.
User token (recommended)10,000 to 50,000 requests, by account tierOAuth through the setup wizard.

On a 429 the server retries with exponential backoff, then reports the error. Track usage in the Developer Portal.

Tools

Each family below is a valid EBAY_MCP_TOOLS value. The table is generated from the tool registry with pnpm readme:tools.

Family (EBAY_MCP_TOOLS key)TitleToolsExample tool
connectorConnector2search
token-managementToken Management10ebay_get_oauth_url
accountAccount51ebay_get_custom_policies
financesFinances11ebay_get_order_earnings
inventoryInventory49ebay_get_document
feedFeed23ebay_get_order_tasks
storesStores8ebay_get_store
fulfillmentFulfillment17ebay_get_cancellation_requests
logisticsLogistics6ebay_get_shipping_quote
marketingMarketing81ebay_get_ads
analyticsAnalytics4ebay_get_traffic_report
metadataMetadata27ebay_get_exclude_shipping_locations
taxonomyTaxonomy8ebay_fetch_item_aspects
communicationCommunication33ebay_find_eligible_items
browseBrowse2ebay_find_active_items
otherOther34ebay_get_user
developerDeveloper7ebay_get_api_status
tradingTrading6ebay_get_active_listings

The full searchable tool list is on the website.

Local media uploads support JPG, PNG, GIF, BMP, TIFF, WEBP, AVIF and HEIC up to 12 MB, and MP4 or MOV up to 150 MB. Files outside EBAY_MCP_MEDIA_DIRS or EBAY_MCP_MEDIA_ROOT are refused, and symlinks are checked before any upload.

MCP Apps (interactive UI cards)

On hosts that support MCP Apps, 15 core read tools show their results as sortable tables, detail cards, charts and stat grids instead of raw JSON. Other hosts get the same data as plain JSON. Set EBAY_MCP_UI=off to turn the views off. The views are read-only and are built by pnpm build.

Run over HTTP

The Docker image starts the HTTP server (node build/serverHttp.js) on port 3000. Set MCP_AUTH_TOKEN to require a static Bearer token. Set MCP_CORS_ORIGINS to allow browser origins other than loopback. See the Dockerfile and docker-compose.yml.

Safety and scope

  • Test in the sandbox first. Tools that create, revise, refund, end or buy (for example postage) change real eBay records in production.
  • Use EBAY_READ_ONLY=true or a short EBAY_MCP_TOOLS list to limit what the assistant can do.
  • Your credentials stay on your machine and go only to eBay.
  • You must follow the eBay API License Agreement and the data-handling requirements, and stay within rate limits.
  • The software is provided "as is" without warranty. See LICENSE.

Troubleshooting

Run npm run diagnose first. Logs go to stderr so they never break the MCP stream.

  • Server not listed in the client: restart the client and check the config path the wizard printed.
  • Auth errors: check the keys, the environment and the RuName. Run the setup wizard again to refresh tokens.
  • 403 Missing x-ebay-signature-key: EU and UK sellers need Digital Signatures. Set both signing variables.
  • Empty results: check EBAY_MARKETPLACE_ID and whether you are on sandbox or production.
  • No interactive views: the host must support MCP Apps, and EBAY_MCP_UI must not be off.

FAQ

Does it work offline? No. The server runs locally but calls eBay's live APIs.

Sandbox and production? Both. Switch with EBAY_ENVIRONMENT.

Can I use it with ChatGPT? Yes, with the connector family. See Tool exposure.

Does it support auctions and the Trading API? Yes. Offers take format: "AUCTION", and the trading family covers legacy XML listings.

How do I update? Run npm install -g ebay-mcp@latest.

Contributing

Fork, branch, add tests, run the checks, then open a PR with Conventional Commits.

pnpm lint && pnpm typecheck && pnpm typecheck:mcp-apps
pnpm test && pnpm build
pnpm readme:tools         # regenerate the tool family table

License

MIT. See LICENSE.

eBay is a trademark of eBay Inc. This project is not affiliated with or endorsed by eBay Inc.

Buy Me A Coffee
NPM
ebay-mcp
Install Command
npm install ebay-mcp