yosefhayim/ebay-mcp

The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay’s Sell APIs. 379 tools for inventory, orders, marketing, and analytics, running locally with your own keys.

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

---

eBay MCP is a local Model Context Protocol server that connects AI assistants — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code, and Amazon Q Developer — directly to eBay’s Sell APIs. It exposes 379 tools spanning 100% of the eBay Sell, Commerce and Developer APIs it tracks (356 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — no cloud relay, and your eBay credentials never leave your computer.

Disclaimer: Unofficial, third-party project — not affiliated with or endorsed by eBay Inc. Provided “as is” without warranty. You are responsible for complying with eBay’s API License Agreement and data-handling requirements, keeping your credentials secure, and staying within rate limits. Test in sandbox before production. See LICENSE.

Table of contents

• Features
• Capability map
• eBay MCP vs. the raw eBay API
• One-click AI setup
• Quick start
• Demo
• Configuration
• Available tools
• Interactive UI (MCP Apps) — beta
• Usage examples
• Scope and safety
• Logging & troubleshooting
• FAQ
• Contributing
• Resources
• License
• Contributors

Features

• 379 eBay API tools — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
• 9 AI clients, auto-configured — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer.
• OAuth 2.0 built in — full user-token management with automatic refresh, and smart fallback from user tokens (10k–50k req/day) to client credentials (1k req/day).
• Resilient by default — automatic retry with exponential backoff on 429 rate limits, and consistent, loud error surfacing.
• Type-safe — TypeScript end to end, Zod-validated tool inputs, and OpenAPI-generated types.
• Local-first & private — runs over STDIO or local HTTP; your credentials and data never leave your machine.
• Sandbox and production — switch environments with a single variable.
• One-command setup — npm run setup configures credentials, OAuth, and your MCP client, with a browser auto-opened for the OAuth flow.
• Well tested — 1,000+ automated tests run in CI on every change through GitHub Actions.

Capability map

Use this map when deciding which tool family to expose, or when asking an assistant what it can do. The family names match EBAY_MCP_TOOLS, so you can run with all tools, dynamic discovery, or only the families needed for a specific workflow.

Listing preflight: required item specifics

Before calling ebay_create_or_replace_inventory_item, ebay_create_offer, or ebay_get_listing_fees, fetch the live requirements for the selected category:

ebay_get_default_category_tree_id → ebay_get_category_suggestions → ebay_get_item_aspects_for_category

The aspects response identifies required and recommended item specifics. Put every required aspect on the inventory item before creating its offer. Requirements vary by category and marketplace, so re-run the lookup when either changes; do not rely on examples or a fixed global fallback value.

Auction offers

ebay_create_offer, ebay_update_offer, and ebay_bulk_create_offer accept both listing formats through the same Inventory model:

Check ebay_get_listing_type_policies for the formats and durations a category allows, then ebay_get_listing_fees before ebay_publish_offer. Bodies that mix the two formats are rejected locally, before any request reaches eBay.

Auctions on the Trading (XML) path

The legacy tools take the same switch as a top-level format argument (FIXED_PRICE by default). ebay_create_listing, ebay_revise_listing, ebay_end_listing, and ebay_relist_item with format: "AUCTION" use the auction-capable calls (AddItem, ReviseItem, EndItem, RelistItem) instead of the *FixedPriceItem family, and ebay_create_listing adds ListingType: "Chinese" to the Item for you:

Mixed payloads are rejected locally. When the format of an existing item is unknown, read its ListingType with ebay_get_listing first (Chinese = auction).

Photos and videos from local files

An offer cannot be published without at least one picture. The media tools upload local files through eBay’s Media API and return what the Inventory API needs:

Local file access is off until you allow it: set EBAY_MCP_MEDIA_DIRS (path-delimited directories) and/or EBAY_MCP_MEDIA_ROOT (one directory that also resolves media:// references). Symlinks are resolved before the containment check; anything outside the allowed directories is refused before any upload. Supported: JPG, PNG, GIF, BMP, TIFF, WEBP, AVIF, HEIC up to 12 MB; MP4/MOV up to 150 MB. Unused uploads expire on eBay’s side; they become permanent once a listing uses them.

Image URLs and documents

These eight tools are also in the inventory family:

For a listing manual, call ebay_create_document with {"documentType":"USER_GUIDE_OR_MANUAL","languages":["ENGLISH"]}, then ebay_upload_document with the returned documentId and "path":"media://manual.pdf". Alternatively, call ebay_create_document_from_url with the same metadata and "documentUrl":"https://example.com/manual.pdf". Use ebay_get_document to check for ACCEPTED before associating the ID with a listing. These calls require user consent for sell.inventory, including the read.

Listing documents accept PDF, JPEG/JPG and PNG up to 10 MiB (10,485,760 bytes). Post-order documents additionally accept BMP and GIF, with a 5 MiB (5,242,880 bytes) limit. Local uploads use the same media allowlist above, with extension and file signature checks. Animated/multi-page PNG is unsupported; use PDF for multi-page content. eBay enforces usage-specific PDF page limits.

For a return label, call ebay_upload_post_order_document with {"path":"media://label.pdf","documentUsageType":"RETURN_SHIPPING_LABEL","entityType":"RETURNS","entityId":"YOUR_RETURN_ID"}. The initial state is SUBMITTED; publication requires a separate eBay GraphQL mutation, outside these tools. Submitted downloads are owner-only; published downloads require authorization in the post-order flow. Published documents cannot be deleted, and expired documents are unavailable.

Post-order tools require an eligible keyset and user consent for https://api.ebay.com/oauth/api_scope/commerce.post_order.document. Add it to your existing EBAY_OAUTH_SCOPES list and repeat OAuth setup/consent. The variable replaces the requested scope list, so retain the other scopes you need. Token refresh does not grant additional scopes. This scope is recognized but is not added to default consent requests. All Media API POST operations are subject to eBay’s user-level limit of 50 requests per five seconds; rate-limit errors are returned to the caller.

See eBay’s Media API overview and release notes.

Finances, feeds, stores, and shipping labels

These families cover the rest of the Sell APIs: Finances, Feed, Stores, Logistics, and Account v2, plus the Metadata shipping, Taxonomy, and Charity endpoints that were missing:

Asynchronous changes. Feed tasks and store category changes return a taskId read from eBay’s Location header (feed schedules return a scheduleId). Poll ebay_get_feed_task or ebay_get_store_task until the task finishes, then fetch any result file. eBay allows one store category change in flight at a time.

Files in and out. Downloads (feed input, result, and schedule files, shipping labels, and the Taxonomy aspect export) come back as embedded MCP resources with base64 bytes; nothing is written to disk. A file over 25 MiB fails with an error as soon as its size is known, without reading the rest. The aspect export for large marketplaces such as EBAY_US exceeds that limit, so use ebay_get_item_aspects_for_category per category there. ebay_upload_feed_task_file reads a local .xml, .csv, .zip, or .gz file of up to 15 MiB (eBay’s data file limit) through the same EBAY_MCP_MEDIA_DIRS / EBAY_MCP_MEDIA_ROOT allowlist as the media tools.

Money moves. ebay_create_shipment_from_shipping_quote buys postage and charges the seller’s billing agreement; ebay_cancel_shipment refunds it while the label is unused.

Optional scopes. Two scopes are recognized but never requested by default:

• https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read for the three order-earnings tools.
• https://api.ebay.com/oauth/api_scope/sell.logistics for every Logistics tool; the API is limited release.

Eligible keysets add the scope to EBAY_OAUTH_SCOPES, keeping the other scopes they need, and repeat OAuth consent.

Digital signatures (EU/UK sellers). eBay requires Digital Signatures on every Finances API call and on issueRefund for sellers domiciled in the EU or UK; without them eBay answers 403 Missing x-ebay-signature-key header. To enable signing:

1. Run ebay_create_signing_key (ED25519 is recommended) and keep the response — eBay never shows the private key again.
2. Set EBAY_SIGNING_KEY_JWE to its jwe and EBAY_SIGNING_PRIVATE_KEY to its privateKey (the base64 value as returned, or a PEM key), then restart the server.

Those calls then carry the x-ebay-signature-key, Content-Digest, Signature-Input, and Signature headers (RFC 9421). Other calls are never signed, and nothing changes while the two variables are unset. Behind EBAY_MCP_API_BASE_URL, calls are signed for the eBay host and path they reach (api.ebay.com or apiz.ebay.com), so the proxy must forward eBay’s Host header and the original eBay path.

eBay MCP vs. the raw eBay API

Both talk to the same eBay endpoints — the difference is everything you’d otherwise build yourself.

One-click AI setup

Let your AI assistant set this up for you. Copy the prompt below and paste it into Claude, ChatGPT, or any AI assistant with MCP support.

Quick start

1. Get eBay credentials

1. Create a free eBay Developer Account.
2. Generate application keys in the Developer Portal.
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.

Demo

See the eBay MCP Server in action with Claude Desktop:

https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b

Configuration

Available tools

Interactive UI (MCP Apps)

Usage examples

Common tasks, phrased as you’d ask your AI assistant:

• Set up OAuth — “Help me set up OAuth for my eBay account.” → generates an authorization URL via ebay_get_oauth_url, then configures the refresh token. Unlocks 10k–50k req/day.
• Manage inventory — “Show me all my active listings.” → ebay_get_inventory_items returns SKUs, quantities, and status.
• Add photos to a listing — “Attach the three photos in ~/listings/megadrive to SKU MD-001.” → ebay_attach_media_to_inventory_item uploads them to eBay Picture Services and updates product.imageUrls (with EBAY_MCP_MEDIA_DIRS allowing that folder).
• Run an auction — “List this SKU as a 7-day auction starting at $9.99 with a $25 reserve.” → ebay_create_offer with format: "AUCTION", auctionStartPrice, auctionReservePrice, and listingDuration: "DAYS_7", then ebay_publish_offer. On the legacy path, ebay_create_listing with format: "AUCTION" and a Trading Item (StartPrice, ReservePrice, ListingDuration: "Days_7").
• Look up offers — ebay_get_offers returns offers for one required SKU. To enumerate offers across the inventory, call ebay_get_inventory_items first, then call ebay_get_offers once per SKU.
• Manage fulfillment policies — “Create a shipping policy, then update its handling time.” → ebay_create_fulfillment_policy creates the reusable policy ID and ebay_update_fulfillment_policy replaces its settings.
• Process orders — “Get all unfulfilled orders from the last 7 days.” → ebay_get_orders with date and fulfillment-status filters.
• Create campaigns — “Create a promoted-listing campaign for electronics.” → ebay_create_campaign and related marketing tools.
• Bulk operations — “Apply a 10% discount to all ‘Vintage Watches’ items.” → ebay_get_inventory_items + ebay_update_offer across matches.

Scope and safety

• Unofficial project. This is not an eBay product and does not grant any additional API rights beyond your own eBay Developer account.
• Local server, live APIs. The MCP server runs on your machine, but tools still call eBay’s sandbox or production APIs over the internet.
• Mutating tools can change seller data. Inventory, fulfillment, marketing, account, feed, stores, and Trading tools may create, revise, refund, end, or otherwise update eBay records, and ebay_create_shipment_from_shipping_quote purchases postage. Test in sandbox first.
• Tool exposure is configurable. Use EBAY_MCP_TOOLS=dynamic or a family list when you want a smaller, workflow-specific tool surface.
• Interactive views are read-only. MCP Apps views can page, refresh, and drill into read tools, but they do not mutate eBay data.
• Compliance remains yours. Keep credentials secure, monitor rate limits, and follow eBay’s API terms and data-handling rules.

Logging & troubleshooting

• Logging — Winston-based, written to stderr (MCP-safe) with optional file output.
• Troubleshooting — server not appearing, auth errors, rate limits, empty results. Start with npm run diagnose.

FAQ

Contributing

Contributions welcome. Fork → branch → add tests → run the checks below → commit with Conventional Commits → open a PR.

pnpm typecheck && pnpm typecheck:mcp-apps   # TypeScript (server + MCP Apps views)
pnpm check:ci                              # Biome lint + format
pnpm test && pnpm test:integration         # Vitest unit + integration
pnpm build                                 # Build to build/

To run the CI gate locally in Docker before pushing, use act: act workflow_dispatch -W .github/workflows/ci.yml. The machine ~/.actrc selects the runner, architecture and shared caches.

Resources

Project docs:

• llms.txt — a compact project summary for AI agents.
• Releases and the Issue Tracker.

Official specs and tooling:

• eBay Developer Portal, Sell API docs, API License Agreement, Data Handling Requirements, and API Status.
• Model Context Protocol and the MCP Apps SDK.
• Node.js, npm package, TypeScript, Zod, Effect, Biome, Vitest, and GitHub Actions.
• Claude Code and llms.txt.

License

MIT — see LICENSE.

Contributors

Thanks to everyone who has helped make this project better! 🎉

---