Skip to main content
Glama
shopping-mcp

shopping-mcp

by Kirat5690

shopping-mcp

An MCP server that lets Claude (or any MCP client) search eBay listings through the official Browse API.

Ask "find me a mechanical keyboard under $100, buy-it-now only, free shipping" and the assistant can actually go and look.

eBay results for "mechanical keyboard" — showing 3 of about 41,208 matches

1. Keychron K8 Pro Wireless Mechanical Keyboard - Brown Switches — $79.99
   total $79.99 · free shipping · New · was $99.00 (19% off)
   seller keeb_supply · 99.6% positive (8421 ratings) · top rated, ships from US
   Item v1|335894120043|0 · https://www.ebay.com/itm/335894120043

2. Ducky One 3 TKL Mechanical Keyboard RGB Hot-Swappable — $84.50
   total $92.45 · $7.95 shipping · New
   seller pc_parts_direct · 98.9% positive (3310 ratings) · accepts offers
   Item v1|326770118254|0 · https://www.ebay.com/itm/326770118254

What it does — and what it deliberately doesn't

Every tool is read-only. This server searches and reads listings. It cannot bid, add to a cart, place an order, or spend money. When you want to buy, it hands you a listing link and you check out yourself.

It's built on the official eBay Browse API — no scraping, no browser automation, no cookie replay. It won't break on a layout change and won't put you in breach of eBay's terms of use.

Related MCP server: ebay-browse-mcp

Tools

Tool

What it's for

search_ebay

Keyword search with price, condition, buying-format, shipping, and location filters.

get_listing_details

Full record for one listing: item specifics, seller, returns, auction end time.

find_deals

Only listings discounted at least N % off their original price, cheapest first.

check_ebay_connection

Show the current config and make a live test call. Run this first when something isn't working.

Two things worth knowing about search_ebay, because they're what eBay has and a fixed-price catalogue doesn't:

  • buying_option filters to auction, buy_it_now, or accepts_offers.

  • sort: "ending_soonest" — combined with buying_option: "auction", that's how you find auctions about to close.

Getting API keys

  1. Sign in at developer.ebay.com/my/keys.

  2. Create an application and open the Production keyset.

  3. Copy the App ID (Client ID) and the Cert ID (Client Secret).

That's all. This server uses the OAuth client-credentials flow, so you do not need a user token, a redirect URI, or an "RuName".

New developer accounts may need to clear eBay's verification before the keys page opens up — that typically takes about a business day.

Install

git clone https://github.com/Kirat5690/shopping-mcp.git
cd shopping-mcp && npm install && npm run build

Connect it to a client

Claude Code

claude mcp add shopping --env EBAY_CLIENT_ID=your-app-id --env EBAY_CLIENT_SECRET=your-cert-id -- node /absolute/path/to/shopping-mcp/dist/index.js

Claude Desktop

Edit claude_desktop_config.json:

  • macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shopping": {
      "command": "node",
      "args": ["C:\\path\\to\\shopping-mcp\\dist\\index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your-app-id",
        "EBAY_CLIENT_SECRET": "your-cert-id",
        "EBAY_MARKETPLACE_ID": "EBAY_US"
      }
    }
  }
}

Restart the client, then ask it to run check_ebay_connection to confirm the credentials work.

Test your keys first (optional, but faster)

Registering a server and restarting a client is a slow way to discover a typo. To check credentials straight away:

EBAY_CLIENT_ID=your-app-id EBAY_CLIENT_SECRET=your-cert-id npm run check

On Windows PowerShell:

$env:EBAY_CLIENT_ID="your-app-id"; $env:EBAY_CLIENT_SECRET="your-cert-id"; npm run check

It prints the resolved configuration, makes one live call, and exits non-zero if anything is wrong. npm run check also reads a .env file if you have one, so cp .env.example .env, fill it in, and just run npm run check.

Configuration reference

Variable

Required

Default

Notes

EBAY_CLIENT_ID

yes

—

App ID from the production keyset.

EBAY_CLIENT_SECRET

yes

—

Cert ID from the same keyset.

EBAY_MARKETPLACE_ID

no

EBAY_US

EBAY_CA, EBAY_GB, EBAY_AU, EBAY_DE, …

EBAY_ENVIRONMENT

no

production

Set to sandbox to use sandbox keys.

EBAY_AFFILIATE_CAMPAIGN_ID

no

—

Returns affiliate-tagged listing links.

EBAY_DELIVERY_POSTAL_CODE

no

—

Improves shipping-cost accuracy.

EBAY_DELIVERY_COUNTRY

no

—

ISO country code, e.g. CA.

SHOPPING_MCP_TIMEOUT_MS

no

15000

Per-request timeout.

Notes on the numbers

  • Landed price is what gets ranked. Sorting by price uses item price plus shipping, so a cheap item with expensive postage doesn't win on a technicality. eBay's own price sort doesn't always do this.

  • Some listings have no total. Where eBay reports shipping as calculated at checkout, there's no landed price until a delivery address is known, and the listing says so rather than guessing.

  • No currency conversion. Prices are shown in the marketplace's own currency, exactly as eBay returns them.

  • Listings are individual sales, not catalogue entries. Two results with near-identical titles can differ in condition, bundle contents, or region. Worth checking before treating them as the same item.

  • find_deals only sees advertised discounts. It filters on eBay's strikethrough "was" price, so a genuinely cheap listing that never claimed a discount won't appear.

Development

npm test

The suite runs without any eBay credentials. It covers the money and landed-price logic, output formatting, and an end-to-end MCP protocol test that boots the server over stdio and exercises tool registration, schema validation, and the unconfigured-credential paths.

npm run watch      # recompile on change
npm run typecheck  # types only, no emit

Layout:

src/
  index.ts     server entry point and stdio wiring
  tools.ts     MCP tool definitions
  ebay.ts      Browse API client and OAuth token cache
  config.ts    environment parsing and marketplace table
  money.ts     price parsing, landed totals, ranking
  format.ts    human-readable output
  http.ts      fetch with timeout and retry

A note on scope

Earlier versions also supported Amazon through the Product Advertising API. That was removed in v0.2.0: PA-API requires an approved Amazon Associates account, and Amazon revokes access if the account makes no qualifying sales — too high a bar for most people to get the server running at all.

The Amazon client and its AWS SigV4 signing are preserved in git history at tag v0.1.0-amazon if you have an approved account and want them back.

Licence

MIT — see LICENSE.

Not affiliated with, endorsed by, or sponsored by eBay. Your use of the eBay API is governed by the eBay API License Agreement.

Available Tools

4 tools
check_ebay_connectionCheck eBay configurationA
Read-only

Report how eBay is configured and make one live test call to confirm the credentials work. Run this first whenever a search fails or returns nothing.

Inputs: no named parameters.

find_dealsFind discounted eBay listingsA
Read-only

Search eBay for listings currently discounted off their original price. Returns only items whose advertised saving meets the threshold, cheapest landed price first.

Inputs: query (required), limit, condition, max_price, +1 more.

get_listing_detailsGet eBay listing detailsA
Read-only

Fetch the full record for one eBay listing: price, condition, availability, seller rating, item specifics, return policy, and auction end time. Accepts either the v1|...|0 item id or the legacy numeric id from an eBay URL.

Inputs: item_id (required).

search_ebaySearch eBay listingsA
Read-only

Search eBay for listings matching a keyword query, with optional price, condition, buying-format, and shipping filters. Returns title, price, shipping, landed total, seller rating, and a link for each listing. Read-only: this never bids, adds to a cart, or places an order.

Inputs: query (required), sort, limit, condition, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 4 tools

    Disambiguation4/5

    Most tools are clearly distinct: check_ebay_connection, search_ebay, get_listing_details each target different actions. search_ebay and find_deals have some overlap, but find_deals is specifically for discounted listings with a savings threshold, so the boundary is clear enough.

    Naming Consistency4/5

    Tool names follow a readable snake_case verb_noun pattern: check_ebay_connection, search_ebay, get_listing_details, find_deals. The only minor inconsistency is using both 'search' and 'find' for similar retrieval actions, but the pattern remains predictable.

    Tool Count4/5

    Four tools is on the small side but appropriate for a focused eBay look-up server. The surface is tight and avoids unnecessary endpoints, though it is slightly minimal for a general 'shopping' MCP.

    Completeness4/5

    The tool set covers the core read-only shopping workflow: connectivity verification, keyword search, deal discovery, and listing details. It intentionally omits purchase actions, and while category browsing or seller info could be added, the current surface is not severely incomplete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search eBay listings, track item prices over time, and identify deals below market value using eBay's APIs. It provides tools for category browsing and retrieving detailed information for specific listings.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Minimal MCP server for searching eBay listings via the Browse API, enabling keyword search with filters, sorting, pagination, and retrieving full item details.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching eBay for auctions by providing a query and number of results, returning auction listings from eBay's Browse REST API.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables eBay product search and item detail retrieval through eBay's official Browse API using app-level OAuth, returning real per-country shipping costs without browser cookies or bot checks.
      MIT