Shopping Deals MCP Server

Shopping Deals MCP Server is a Model Context Protocol server for finding products, comparing marketplace listings, and ranking the cheapest real offers across eBay, Amazon, Craigslist, and OfferUp.

It is built for agents that need to answer questions like:

• "Find the cheapest DJI OSMO Pocket 4P shipped to me."

• "Compare exact-model prices across marketplaces."

• "Avoid accessory listings, wrong variants, and fake low prices with high shipping."

• "Estimate tax and sort by final landed cost."

What It Does

• Searches multiple shopping sources from one MCP interface.

• Normalizes listings into a common schema.

• Separates item price, shipping cost, shipped total, estimated tax, and estimated final total.

• Penalizes accessories, parts, and wrong model variants.

• Handles edge cases like Pocket 4P vs Pocket 4.

• Can run locally over stdio or remotely as a Cloudflare Worker MCP endpoint.

Related MCP server: Bargainer MCP Server

MCP Tools

Sources

Scraped/public sources can change or block automated traffic. Official APIs are more reliable.

Requirements

• Python 3.10+

• Node.js 20+ for the Cloudflare Worker version

• eBay developer credentials for reliable eBay results

• Optional: SerpApi key for broad Google Shopping coverage

• Optional: Cloudflare account for remote hosting

Quick Start: Local MCP Server

git clone https://github.com/jongan69/shopping-deals-mcp-server.git
cd shopping-deals-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Edit .env with your own credentials:

EBAY_APP_ID=your-ebay-client-id
EBAY_CERT_ID=your-ebay-client-secret
EBAY_DEV_ID=your-ebay-dev-id
EBAY_MARKETPLACE_ID=EBAY_US
EBAY_USE_SANDBOX=false
SHOPPING_ENABLE_AMAZON_SCRAPE=true

Run over stdio:

shopping-deals-mcp --transport stdio

Run over Streamable HTTP for local testing:

shopping-deals-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Local HTTP MCP endpoint:

http://127.0.0.1:8000/mcp

Add To Codex

Local stdio server:

codex mcp add shopping-deals -- /absolute/path/to/shopping-deals-mcp-server/.venv/bin/shopping-deals-mcp --transport stdio

Remote Streamable HTTP server:

codex mcp add shopping-deals-remote --url https://your-worker.your-subdomain.workers.dev/mcp

Verify:

codex mcp get shopping-deals-remote

Add To Any MCP Client

Use the local stdio command:

{
  "mcpServers": {
    "shopping-deals": {
      "command": "/absolute/path/to/shopping-deals-mcp-server/.venv/bin/shopping-deals-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Or use a remote Streamable HTTP endpoint:

https://your-worker.your-subdomain.workers.dev/mcp

Cloudflare Worker Deployment

This repo includes a TypeScript Worker implementation for remote MCP clients.

Install dependencies:

npm install
cp .env .dev.vars
npm run typecheck
npm run dev -- --port 8787

Test locally:

http://127.0.0.1:8787/health
http://127.0.0.1:8787/mcp

Before deploying, change the Worker name in wrangler.jsonc if shopping-deals-mcp is already taken in your Cloudflare account:

{
  "name": "your-shopping-deals-mcp"
}

Upload secrets:

printf '%s' "$EBAY_APP_ID" | npx wrangler secret put EBAY_APP_ID
printf '%s' "$EBAY_CERT_ID" | npx wrangler secret put EBAY_CERT_ID
printf '%s' "$EBAY_DEV_ID" | npx wrangler secret put EBAY_DEV_ID

Deploy:

npm run deploy

Your remote MCP endpoint will be:

https://your-worker.your-subdomain.workers.dev/mcp

Optional Tax Estimates

eBay Browse search results do not return the buyer's final checkout tax amount. This server supports estimated tax when you provide a tax rate.

Set defaults:

SHOPPING_ESTIMATED_TAX_RATE_PERCENT=8.875
SHOPPING_TAX_SHIPPING=true

Or pass per tool call:

{
  "query": "DJI OSMO Pocket 4P",
  "sources": ["ebay"],
  "max_results": 5,
  "max_results_per_source": 50,
  "tax_rate_percent": 8.875,
  "tax_on_shipping": true
}

Returned listings can include:

• price

• shipping_cost

• total_price

• estimated_tax

• total_with_tax

Use find_cheapest_offers when the goal is the lowest estimated final cost.

Example Tool Calls

Find the cheapest exact-model offer by shipped total plus estimated tax:

{
  "query": "DJI OSMO Pocket 4P",
  "sources": ["ebay"],
  "max_results": 10,
  "max_results_per_source": 50,
  "tax_rate_percent": 8.875,
  "tax_on_shipping": true
}

Find ranked deals across marketplaces:

{
  "query": "sony wh-1000xm5 headphones",
  "sources": ["ebay", "craigslist", "offerup", "amazon"],
  "max_results": 10,
  "max_results_per_source": 20,
  "condition": "any"
}

Compare prices:

{
  "query": "macbook air m2 16gb",
  "sources": ["ebay", "craigslist", "offerup"],
  "location": "newyork",
  "max_results_per_source": 15
}

Configuration

Development

Python checks:

source .venv/bin/activate
pytest
ruff check .

Worker checks:

npm install
npm run typecheck

License

MIT

Notes And Limitations

• Deal scores are triage signals, not purchase guarantees.

• Always verify seller reputation, return policy, warranty, shipping, taxes, and authenticity before buying.

• Amazon, Craigslist, and OfferUp public parsers may break if those sites change markup or block traffic.

• Craigslist RSS returns HTTP 403 from Cloudflare Worker egress, so the Worker uses Craigslist static search HTML cards.

• Tax is estimated from a supplied rate. Final checkout tax may differ.