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, Facebook Marketplace, 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."

• "Compare the same item across Miami, New York, Los Angeles, and other local markets."

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

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

• "Find marketplace items I can buy and flip profitably on eBay."

• "Research whether a used car is worth flipping on eBay Motors before I inspect it."

• "Track Florida dealer-threshold exposure while evaluating vehicle flips."

• "Track resale leads, inventory, listed items, sold items, and business metrics."

What It Does

• Searches multiple shopping sources from one MCP interface.

• Normalizes listings into a common schema.

• Defaults OfferUp searches to Miami Beach while allowing explicit location overrides.

• 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.

• Scores reseller/arbitrage opportunities using eBay comps, estimated fees, shipping, tax, ROI, and risk.

• Scores vehicle flips separately with eBay Motors listing fees, title/VIN risk, transport, inspection, repairs, storage, and Florida dealer-threshold awareness.

• Tracks a simple resale pipeline: leads, purchases, inventory, listings, sold items, and realized profit.

• 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

Use The Hosted MCP Server

You can use the public hosted MCP server without cloning this repo:

https://shopping-deals-mcp.jonathang132298.workers.dev/mcp

Add it to Codex:

codex mcp add shopping-deals-remote --url https://shopping-deals-mcp.jonathang132298.workers.dev/mcp
codex mcp get shopping-deals-remote

Use it from any MCP client that supports Streamable HTTP:

{
  "mcpServers": {
    "shopping-deals": {
      "url": "https://shopping-deals-mcp.jonathang132298.workers.dev/mcp"
    }
  }
}

Health and source status:

https://shopping-deals-mcp.jonathang132298.workers.dev/health

The hosted Worker uses the maintainer's configured API keys and public marketplace parsers. If you want to use your own eBay, SerpApi, or Cloudflare account, follow the local setup or deployment steps below.

The hosted Worker exposes the reseller and vehicle research tools. Stateful business tools require the Worker's RESALE_KV binding; if a deployment has no KV binding, stateless tools such as find_arbitrage_opportunities, find_vehicle_arbitrage_opportunities, calculate_resale_profit, calculate_vehicle_flip_profit, get_ebay_sold_comps, decode_vin, and listing-draft tools still work, while lead/inventory tools return a clear persistence configuration error.

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
EBAY_REDIRECT_URI=your-ebay-oauth-redirect-uri-or-runame
# Optional single-seller shortcut. Prefer OAuth/KV for production.
EBAY_SELLER_REFRESH_TOKEN=your-connected-seller-refresh-token
SHOPPING_ENABLE_AMAZON_SCRAPE=true
SHOPPING_FACEBOOK_MARKETPLACE_LATITUDE=40.7128
SHOPPING_FACEBOOK_MARKETPLACE_LONGITUDE=-74.0060
SHOPPING_OFFERUP_DEFAULT_CITY=Miami Beach
SHOPPING_OFFERUP_DEFAULT_STATE=FL
SHOPPING_OFFERUP_DEFAULT_ZIP=33139
SHOPPING_OFFERUP_DEFAULT_LATITUDE=25.7907
SHOPPING_OFFERUP_DEFAULT_LONGITUDE=-80.1300
SHOPPING_OFFERUP_RADIUS_MILES=30
SHOPPING_RESALE_STORE_PATH=.shopping-deals/resale-business.json

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://shopping-deals-mcp.jonathang132298.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://shopping-deals-mcp.jonathang132298.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
printf '%s' "$EBAY_REDIRECT_URI" | npx wrangler secret put EBAY_REDIRECT_URI

Create and bind KV for resale lead/inventory persistence:

npx wrangler kv namespace create RESALE_KV

Add the returned namespace ID to wrangler.jsonc:

{
  "kv_namespaces": [
    {
      "binding": "RESALE_KV",
      "id": "your-kv-namespace-id"
    }
  ]
}

Deploy:

npm run deploy

Your remote MCP endpoint will be:

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

eBay Seller Automation

The seller-write tools let an agent help run an eBay sales workflow: connect a seller account, check seller readiness, create inventory, upload listing videos, create offers, publish listings, fetch orders, and add shipment tracking.

Seller-write tools require a seller user token. The app keyset belongs to the MCP operator, but listing/order calls act on the eBay account that authorized OAuth. For a multi-user setup, each seller must connect their own eBay account and the Worker stores that seller's refresh token in RESALE_KV.

Recommended connection flow:

1. Call ebay_seller_connect_url.

2. Open the returned authorization_url and approve access as the eBay seller.

3. Copy the returned authorization code.

4. Call ebay_exchange_seller_code with that code.

5. Call ebay_seller_connection_status.

6. Call ebay_get_seller_policies to retrieve fulfillment/payment/return policies and inventory locations.

7. If the account has no policies yet, call ebay_create_default_seller_policies. The helper reuses existing policies when possible and handles eBay duplicate-policy responses as reuse.

Before publishing, the seller account must have:

• Business policies enabled.

• Payment, return, and fulfillment policies.

• At least one inventory location.

• Valid category ID, condition, required item specifics/aspects, price, quantity, and images.

• Enough eBay seller limits for the listing.

Listing workflow:

1. Use draft_ebay_listing to prepare title, description, photo checklist, disclosures, and pricing guidance.

2. Use ebay_upsert_inventory_item to create/update the SKU.

3. Use ebay_create_offer to create the offer.

4. Use ebay_publish_offer only after reviewing the final payload.

For a single combined flow, use ebay_create_listing_workflow. It defaults to review mode: it creates inventory and an offer but does not publish unless publish_immediately is explicitly set to true.

Listing video workflow:

1. Host the video at a temporary URL the Worker can fetch.

2. Call ebay_create_video_upload.

3. Poll ebay_get_video until eBay finishes processing.

4. Add the returned video_id to video_ids in ebay_upsert_inventory_item.

Listing conversion workflow:

1. Call ebay_get_listing_performance_dashboard to audit every active listing.

2. Use ebay_save_listing_performance_snapshot before making changes.

3. Call ebay_get_listing_asset_workbench for the target listings. This returns the actual eBay photo URLs, safe local download commands, and AI edit/video briefs that require those real photos as references.

4. Download the actual product photos locally and inspect them.

5. Improve the actual listing media: add real item photos, make conservative reference-based AI edits, upload approved images with ebay_create_image_from_url, upload videos with ebay_create_video_upload, and stage live media updates with ebay_revise_listing_media.

6. Keep apply_immediately=false until a human has reviewed the staged photo/video payload.

7. After the listings have had time to collect traffic, save another snapshot and call ebay_compare_listing_performance_snapshots.

Actual-photo AI asset workflow:

1. Use ebay_get_listing_asset_workbench with one or more item_ids.

2. Run the returned download_commands, or download from the returned manifest URLs, into the listed output folder.

3. Use those downloaded files as required reference images in your image or video tool.

4. Keep edits as close to the real asset as possible: crop, straighten, exposure, white balance, background cleanup, sharper composition, and inspection-friendly detail crops.

5. Do not add missing accessories, remove real flaws, change condition, alter labels/model details, fake operation, or generate unreferenced angles/details.

6. Keep originals and edited outputs together so an agent can audit what changed.

7. Host finished assets at HTTPS URLs, upload them through ebay_create_image_from_url or ebay_create_video_upload, then stage changes with ebay_revise_listing_media.

The dashboard combines eBay listing state with asset quality signals: photo count, video count, title usage, description length, bids, watches, views, and eBay Analytics traffic metrics when the connected seller token has Analytics access. Traffic metrics can include impressions, total views, click-through rate, sales conversion rate, and transactions.

For used or pre-owned items, keep the primary image as a real photo of the actual item. AI-generated or edited assets should only improve presentation, such as background cleanup or a supplemental promo visual, and must not change condition, included contents, flaws, serial/model details, or anything a buyer relies on.

Listing photo workflow:

1. Host the finished image at an HTTPS URL.

2. Call ebay_create_image_from_url.

3. If needed, call ebay_get_image with the returned image ID.

4. Use the returned EPS imageUrl in ebay_revise_listing_media as part of the complete picture_urls array.

Direct Trading API media workflow for existing listings:

1. Call ebay_get_listing_detail or ebay_get_listing_performance_dashboard to capture the current picture_urls and video_ids.

2. Build the complete desired replacement array. eBay media revision replaces the listing's submitted photo/video fields; do not send only one new photo unless you intentionally want only that one photo.

3. Call ebay_revise_listing_media with apply_immediately=false.

4. After review, rerun with apply_immediately=true.

Order fulfillment workflow:

1. Call ebay_get_orders.

2. Ship the item using your carrier workflow.

3. Call ebay_add_order_tracking with the eBay order ID, carrier code, tracking number, and line items.

The MCP is designed for legitimate seller optimization: better listings, better photos/videos, price discipline, fast fulfillment, and complete disclosures. It should not be used for counterfeit goods, spam listings, misleading descriptions, review manipulation, policy evasion, or any other activity that violates eBay policy.

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", "facebook_marketplace", "craigslist", "offerup", "amazon"],
  "location": "40.7128,-74.0060",
  "max_results": 10,
  "max_results_per_source": 20,
  "condition": "any"
}

Find possible eBay flips:

{
  "query": "Sony a6700 camera body",
  "buy_sources": ["facebook_marketplace", "craigslist", "offerup", "ebay"],
  "location": "40.7128,-74.0060",
  "max_results": 10,
  "max_results_per_source": 25,
  "price_max": 700,
  "min_profit": 75,
  "min_roi_percent": 20,
  "purchase_tax_rate_percent": 8.875,
  "outbound_shipping": 18
}

Calculate resale profit directly:

{
  "purchase_price": 500,
  "expected_sale_price": 775,
  "inbound_shipping": 0,
  "outbound_shipping": 18,
  "purchase_tax_rate_percent": 8.875,
  "platform_fee_percent": 13.25,
  "packing_cost": 2
}

Save a lead and track it through inventory:

{
  "lead": {
    "title": "Sony a6700 camera body",
    "source": "facebook_marketplace",
    "url": "https://www.facebook.com/marketplace/item/example",
    "asking_price": 575,
    "expected_sale_price": 775,
    "status": "watching"
  }
}

Then use:

• update_resale_lead_status

• create_inventory_item

• mark_inventory_listed

• mark_inventory_sold

• calculate_business_metrics

Research a possible car flip:

{
  "query": "2012 Honda Fit Miami",
  "buy_sources": ["facebook_marketplace", "craigslist", "offerup"],
  "location": "25.7907,-80.1300",
  "max_results": 5,
  "max_results_per_source": 20,
  "price_max": 7000,
  "min_profit": 2000,
  "min_roi_percent": 20,
  "repair_cost": 750,
  "transport_cost": 500,
  "inspection_cost": 150,
  "detail_cost": 150,
  "title_registration_cost": 450,
  "sales_tax_rate_percent": 0,
  "vehicles_sold_or_offered_12mo": 0,
  "title_status": "unknown",
  "has_title_in_hand": null
}

Calculate vehicle profit directly:

{
  "purchase_price": 7000,
  "expected_sale_price": 10500,
  "repair_cost": 500,
  "transport_cost": 400,
  "inspection_cost": 150,
  "detail_cost": 150,
  "title_registration_cost": 450
}

Track vehicle compliance risk:

{
  "vehicles_sold_or_offered_12mo": 2,
  "planned_new_vehicle_offers": 1
}

Reselling Notes

get_ebay_sold_comps is intentionally conservative: today it uses active eBay listing comps as a clearly labeled proxy because the current public eBay Browse API integration does not provide completed/sold listing data. Active comps are useful for initial triage, but confirmed sold comps are better for pricing and sell-through confidence. If you have access to a completed-listing data provider, add it as a dedicated source and keep the basis field explicit.

The arbitrage score is a triage signal. Before buying, verify exact model, condition, serial/authenticity, locks/accounts, missing accessories, seller reputation, local safety, shipping dimensions, return risk, and final marketplace fees.

Vehicle flips are scored with a separate model. eBay Motors vehicle listings use package fees instead of the normal item final-value fee model; this server defaults to $34 at $15,000 or less and $79 above $15,000, matching eBay's current public help page at the time of implementation. Florida has a low dealer-activity threshold: three or more vehicles bought, sold, dealt, offered, or displayed for sale in a 12-month period creates a prima facie presumption of motor vehicle dealer activity. This server surfaces that threshold, but it does not provide legal advice.

Before buying a vehicle, verify title in hand, VIN match, lien status, odometer, accident/flood history, seller identity, mechanical condition, storage, transport, insurance, tax/title fees, and your legal ability to resell.

Search Facebook Marketplace near New York City:

{
  "query": "used bike",
  "sources": ["facebook_marketplace"],
  "location": "40.7128,-74.0060",
  "max_results_per_source": 10
}

Compare prices:

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

Compare local areas:

{
  "query": "Sony FE 35mm lens",
  "sources": ["offerup"],
  "areas": ["Miami Beach, FL", "Miami, FL", "New York, NY", "Los Angeles, CA"],
  "max_results_per_area": 15,
  "price_max": 800
}

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.

• Arbitrage scores are triage signals, not guarantees of sell-through, profit, authenticity, or buyer demand.

• Vehicle opportunity scores are research signals, not legal, title, mechanical, tax, insurance, or dealer-licensing advice.

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

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

• Facebook Marketplace support is experimental. It uses Facebook's public Marketplace web feed with an anonymous page token and requires a local search center.

• OfferUp location is set with OfferUp's public ou.location cookie. Some markets may still be influenced by OfferUp ranking and availability.

• 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.

• eBay sold-comps support currently uses active listing comps as a labeled proxy until a true completed/sold-listing data provider is configured.

• Vehicle comps currently use active eBay listing data as a market proxy. Confirm sold results, trim, mileage, title status, accident history, location, and vehicle history before buying.