Skip to content
Back to search

ebay-mcp

Local MCP server that connects AI assistants to eBay seller APIs for listings, orders, and marketing, with OAuth setup.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/YosefHayim/ebay-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/YosefHayim/ebay-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yosefhayim--ebay-mcp/badge.svg)](/listings/yosefhayim--ebay-mcp)

HTML

<a href="/listings/yosefhayim--ebay-mcp"><img src="/api/listings/yosefhayim--ebay-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Get eBay credentials

1. Create a free [eBay Developer Account](https://developer.ebay.com/). 2. Generate application keys in the [Developer Portal](https://developer.ebay.com/my/keys). 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.

<details> <summary><strong>📸 Visual setup walkthrough (eBay Developer Portal)</strong></summary>

<br />

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](https://developer.ebay.com/my/keys), 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).

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://github.com/YosefHayim/ebay-mcp"><img src=".github/readme/ebay-mcp-hero.png" alt="eBay MCP server: connect Claude, Cursor and other AI assistants to eBay's Sell APIs" width="820" /></a>
  3. </p>
  4. <p align="center">
  5. <strong>A local MCP server that gives AI assistants 379 tools for the eBay Sell, Commerce and Developer APIs, running with your own keys.</strong>
  6. </p>
  7. <p align="center"><sub>Unofficial open-source project. Not affiliated with, authorized or endorsed by eBay Inc.</sub></p>
  8. <p align="center">
  9. <a href="https://www.npmjs.com/package/ebay-mcp"><img src="https://img.shields.io/npm/v/ebay-mcp?logo=npm&color=cb3837" alt="npm version" /></a>
  10. <a href="https://www.npmjs.com/package/ebay-mcp"><img src="https://img.shields.io/npm/dm/ebay-mcp?logo=npm&color=cb3837" alt="npm downloads per month" /></a>
  11. <a href="https://github.com/YosefHayim/ebay-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/ebay-mcp/ci.yml?branch=main&logo=github&label=CI" alt="CI status" /></a>
  12. <a href="LICENSE"><img src="https://img.shields.io/npm/l/ebay-mcp?color=blue" alt="MIT license" /></a>
  13. <img src="https://img.shields.io/badge/tools-379-8957e5?logo=ebay&logoColor=white" alt="379 eBay API tools" />
  14. </p>
  15. <p align="center">
  16. <a href="https://yosefhayim.github.io/ebay-mcp/">Website</a> ·
  17. <a href="https://www.npmjs.com/package/ebay-mcp">npm</a> ·
  18. <a href="https://github.com/YosefHayim/ebay-mcp/releases">Releases</a>
  19. </p>
  20. ## What it does
  21. - Connects Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code and Amazon Q Developer to eBay. Any MCP client can connect.
  22. - Covers inventory, orders, fulfillment, finances, feeds, stores, shipping labels, promoted listings, analytics, taxonomy, messaging and the legacy Trading API.
  23. - Handles OAuth 2.0 with automatic token refresh, and retries `429` rate limits with backoff.
  24. - Validates every tool input with Zod and uploads local photos and videos through the Media API.
  25. - Runs on your machine over STDIO or HTTP. There is no cloud relay and your credentials stay local.
  26. - Works with the eBay sandbox and production. One variable switches between them.
  27. ## Quick start
  28. ### 1. Get eBay keys
  29. Create a free [eBay Developer Account](https://developer.ebay.com/). In the [Developer Portal](https://developer.ebay.com/my/keys), copy the **App ID (Client ID)** and **Cert ID (Client Secret)**.
  30. ![Step 1: copy the Client ID and Client Secret from the eBay Developer Portal](.github/readme/setup-step-1-copy-client-id-and-secret.png)
  31. In your app's **User Tokens** settings, copy the **RuName** (the eBay redirect URL).
  32. ![Step 2: copy the RuName redirect URL](.github/readme/setup-step-2-copy-redirect-url.png)
  33. ### 2. Run the setup wizard
  34. Needs [Node.js](https://nodejs.org/) 24 or newer.
  35. ```bash
  36. npm install -g ebay-mcp
  37. npx ebay-mcp setup # or: npm run setup, from a source checkout
  38. ```
  39. The wizard saves your credentials, opens the browser for eBay sign-in and configures your MCP client.
  40. ![Step 3: sign in to eBay during the OAuth flow](.github/readme/setup-step-3-run-setup-and-oauth-login.png)
  41. Paste the authorization code from the callback URL when it asks.
  42. ![Step 4: paste the authorization code into the setup wizard](.github/readme/setup-step-4-paste-into-setup-wizard.png)
  43. Watch the [video tutorial](.github/readme/video-tutorial.mp4) for the full flow.
  44. ### 3. Verify with a read-only request
  45. 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.
  46. ### 4. Use it
  47. Start with read-only questions. Move to tools that change data only after you confirm whether you are on sandbox or production.
  48. To add the server by hand, use the Claude Code one-liner:
  49. ```bash
  50. 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
  51. ```
  52. Or add this to any MCP client config:
  53. ```json
  54. {
  55. "mcpServers": {
  56. "ebay": {
  57. "command": "npx",
  58. "args": ["-y", "ebay-mcp"],
  59. "env": {
  60. "EBAY_CLIENT_ID": "your_client_id",
  61. "EBAY_CLIENT_SECRET": "your_client_secret",
  62. "EBAY_ENVIRONMENT": "sandbox",
  63. "EBAY_REDIRECT_URI": "your_runame",
  64. "EBAY_USER_REFRESH_TOKEN": "your_refresh_token"
  65. }
  66. }
  67. }
  68. }
  69. ```
  70. ## Configuration
  71. The setup wizard writes the variables for you. See [`.env.example`](.env.example) for the full list.
  72. | Variable | Default | What it does |
  73. | --- | --- | --- |
  74. | `EBAY_CLIENT_ID`, `EBAY_CLIENT_SECRET` | none | Your eBay app keys. |
  75. | `EBAY_ENVIRONMENT` | `sandbox` | `sandbox` or `production`. |
  76. | `EBAY_REDIRECT_URI` | none | The RuName used for OAuth sign-in. |
  77. | `EBAY_USER_REFRESH_TOKEN` | none | User token for higher rate limits. |
  78. | `EBAY_OAUTH_SCOPES` | default scopes | Replaces the requested scope list. Keep the scopes you need. |
  79. | `EBAY_MARKETPLACE_ID` | `EBAY_US` | Default marketplace, overridable per tool. |
  80. | `EBAY_SITE_ID` | from marketplace | Trading API site override. |
  81. | `EBAY_CONTENT_LANGUAGE` | `en-US` | Default request content language. |
  82. | `EBAY_MCP_TOOLS` | `all` | Which tools are advertised. See below. |
  83. | `EBAY_READ_ONLY` | `false` | When `true`, only read-only tools are registered. |
  84. | `EBAY_MCP_UI` | `on` | `off` forces plain JSON instead of interactive views. |
  85. | `EBAY_MCP_MEDIA_DIRS`, `EBAY_MCP_MEDIA_ROOT` | none | Directories the media and feed upload tools may read. Off until set. |
  86. | `EBAY_SIGNING_KEY_JWE`, `EBAY_SIGNING_PRIVATE_KEY` | none | Digital Signatures for EU and UK sellers. Both come from `ebay_create_signing_key`. |
  87. | `MCP_PORT`, `MCP_HOST`, `MCP_AUTH_TOKEN`, `MCP_CORS_ORIGINS` | none | HTTP mode settings. See [Run over HTTP](#run-over-http). |
  88. ### Tool exposure
  89. A full catalogue takes a lot of context window. `EBAY_MCP_TOOLS` shrinks it:
  90. | Value | Behavior |
  91. | --- | --- |
  92. | `all` (default) | Every tool is advertised at startup. |
  93. | `dynamic` | Three 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. |
  94. | `inventory,fulfillment` | Only the named families, fixed for the session. Works on every host. |
  95. 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.
  96. ### Read-only mode
  97. Set `EBAY_READ_ONLY=true` to register only tools that read data (gets, lists, searches). Use it for first runs and for reporting assistants.
  98. ### Authentication and rate limits
  99. | Mode | Daily limit | Setup |
  100. | --- | --- | --- |
  101. | Client credentials (default) | 1,000 requests | Automatic with Client ID and Secret. |
  102. | User token (recommended) | 10,000 to 50,000 requests, by account tier | OAuth through the setup wizard. |
  103. On a `429` the server retries with exponential backoff, then reports the error. Track usage in the [Developer Portal](https://developer.ebay.com/my/api_usage).
  104. ## Tools
  105. Each family below is a valid `EBAY_MCP_TOOLS` value. The table is generated from the tool registry with `pnpm readme:tools`.
  106. <!-- tool-families:start -->
  107. | Family (`EBAY_MCP_TOOLS` key) | Title | Tools | Example tool |
  108. | --- | --- | --- | --- |
  109. | `connector` | Connector | 2 | `search` |
  110. | `token-management` | Token Management | 10 | `ebay_get_oauth_url` |
  111. | `account` | Account | 51 | `ebay_get_custom_policies` |
  112. | `finances` | Finances | 11 | `ebay_get_order_earnings` |
  113. | `inventory` | Inventory | 49 | `ebay_get_document` |
  114. | `feed` | Feed | 23 | `ebay_get_order_tasks` |
  115. | `stores` | Stores | 8 | `ebay_get_store` |
  116. | `fulfillment` | Fulfillment | 17 | `ebay_get_cancellation_requests` |
  117. | `logistics` | Logistics | 6 | `ebay_get_shipping_quote` |
  118. | `marketing` | Marketing | 81 | `ebay_get_ads` |
  119. | `analytics` | Analytics | 4 | `ebay_get_traffic_report` |
  120. | `metadata` | Metadata | 27 | `ebay_get_exclude_shipping_locations` |
  121. | `taxonomy` | Taxonomy | 8 | `ebay_fetch_item_aspects` |
  122. | `communication` | Communication | 33 | `ebay_find_eligible_items` |
  123. | `browse` | Browse | 2 | `ebay_find_active_items` |
  124. | `other` | Other | 34 | `ebay_get_user` |
  125. | `developer` | Developer | 7 | `ebay_get_api_status` |
  126. | `trading` | Trading | 6 | `ebay_get_active_listings` |
  127. <!-- tool-families:end -->
  128. The full searchable tool list is on the [website](https://yosefhayim.github.io/ebay-mcp/).
  129. 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.
  130. ## MCP Apps (interactive UI cards)
  131. On hosts that support [MCP Apps](https://modelcontextprotocol.io), 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`.
  132. ## Run over HTTP
  133. 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](Dockerfile) and [docker-compose.yml](docker-compose.yml).
  134. ## Safety and scope
  135. - Test in the sandbox first. Tools that create, revise, refund, end or buy (for example postage) change real eBay records in production.
  136. - Use `EBAY_READ_ONLY=true` or a short `EBAY_MCP_TOOLS` list to limit what the assistant can do.
  137. - Your credentials stay on your machine and go only to eBay.
  138. - You must follow the [eBay API License Agreement](https://developer.ebay.com/join/api-license-agreement) and the [data-handling requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html), and stay within rate limits.
  139. - The software is provided "as is" without warranty. See [LICENSE](LICENSE).
  140. ## Troubleshooting
  141. Run `npm run diagnose` first. Logs go to stderr so they never break the MCP stream.
  142. - **Server not listed in the client:** restart the client and check the config path the wizard printed.
  143. - **Auth errors:** check the keys, the environment and the RuName. Run the setup wizard again to refresh tokens.
  144. - **`403 Missing x-ebay-signature-key`:** EU and UK sellers need Digital Signatures. Set both signing variables.
  145. - **Empty results:** check `EBAY_MARKETPLACE_ID` and whether you are on sandbox or production.
  146. - **No interactive views:** the host must support MCP Apps, and `EBAY_MCP_UI` must not be `off`.
  147. ### FAQ
  148. **Does it work offline?** No. The server runs locally but calls eBay's live APIs.
  149. **Sandbox and production?** Both. Switch with `EBAY_ENVIRONMENT`.
  150. **Can I use it with ChatGPT?** Yes, with the `connector` family. See Tool exposure.
  151. **Does it support auctions and the Trading API?** Yes. Offers take `format: "AUCTION"`, and the `trading` family covers legacy XML listings.
  152. **How do I update?** Run `npm install -g ebay-mcp@latest`.
  153. ## Contributing
  154. Fork, branch, add tests, run the checks, then open a PR with [Conventional Commits](https://www.conventionalcommits.org/).
  155. ```bash
  156. pnpm lint && pnpm typecheck && pnpm typecheck:mcp-apps
  157. pnpm test && pnpm build
  158. pnpm readme:tools # regenerate the tool family table
  159. ```
  160. ## License
  161. MIT. See [LICENSE](LICENSE).
  162. eBay is a trademark of eBay Inc. This project is not affiliated with or endorsed by eBay Inc.
  163. <div align="center">
  164. <a href="https://www.buymeacoffee.com/yosefhayim"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="48" /></a>
  165. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.