Shopping Deals 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.

MCP Tools

Tool	Purpose
list_sources	Show configured sources and setup requirements.
search_products	Return normalized listings across selected platforms.
find_best_deals	Rank strongest deals using price, relevance, condition, source, and warnings.
find_cheapest_offers	Filter exact-model offers and sort by shipped total plus estimated tax when supplied.
compare_prices	Group comparable listings and summarize observed price ranges.
compare_area_prices	Search the same product across multiple areas and compare local listing price ranges.
get_listing_details	Fetch source-specific listing details where supported.
get_ebay_sold_comps	Estimate resale value from eBay comps. Currently returns active-listing comps as a labeled proxy, not fabricated sold data.
calculate_resale_profit	Calculate eBay-style flip profit, ROI, fees, tax, break-even sale price, and max buy price.
find_arbitrage_opportunities	Search buy-side marketplaces and rank listings that may be profitable to resell on eBay.
draft_ebay_listing	Draft an eBay title, description, price hint, shipping guidance, and photo/disclosure checklist.
ebay_seller_connect_url	Create the OAuth consent URL for connecting an eBay seller account.
ebay_exchange_seller_code	Exchange an eBay authorization code and store the seller refresh token in Worker KV.
ebay_seller_connection_status	Check seller-token configuration and retrieve the connected eBay user profile when possible.
ebay_get_seller_policies	Fetch seller business policies, inventory locations, and account readiness.
ebay_create_seller_policy	Create a specific eBay payment, return, or fulfillment policy from an Account API payload.
ebay_create_default_seller_policies	Create or reuse default payment, return, and USPS Priority shipping policies.
ebay_create_inventory_location	Create the inventory location required before publishing listings.
ebay_upsert_inventory_item	Create or update an eBay Inventory API SKU with title, description, photos, aspects, quantity, and videos.
ebay_get_inventory_items	List Inventory API items for the connected seller account.
ebay_get_offers	List Inventory API offers for a specific connected seller SKU.
ebay_get_selling_listings	List active My eBay selling listings using the Trading API, including listings not created by this MCP.
ebay_get_listing_detail	Fetch detailed title, description, category, photos, item specifics, and selling status for one listing.
ebay_get_listing_asset_workbench	Return actual listing photo URLs, local download commands, edit briefs, video prompts, and upload/revise steps for AI-assisted asset work.
ebay_revise_listing_copy	Preview or apply live eBay title/description revisions through Trading API.
ebay_get_traffic_report	Fetch eBay Analytics listing/day traffic metrics such as impressions, views, CTR, conversion rate, and transactions.
ebay_get_listing_performance_dashboard	Audit active listing assets and performance signals, including photo/video counts, watches, bids, views, and traffic when available.
ebay_save_listing_performance_snapshot	Save a listing performance dashboard into Worker KV for before/after optimization tracking.
ebay_compare_listing_performance_snapshots	Compare two saved snapshots and return listing-level deltas.
ebay_create_image_from_url	Upload an HTTPS image URL to eBay Picture Services and return the EPS image URL/image ID.
ebay_get_image	Retrieve eBay Media API image details after upload.
ebay_revise_listing_media	Preview or apply live eBay photo/video revisions through Trading API.
ebay_create_offer	Create an eBay offer for a SKU without publishing it.
ebay_publish_offer	Publish an offer as a live eBay listing.
ebay_create_listing_workflow	Create inventory, create an offer, and optionally publish after explicit approval.
ebay_create_video_upload	Create a listing video asset and upload video bytes from a URL.
ebay_get_video	Check listing video processing status.
ebay_get_orders	Fetch seller orders from eBay Fulfillment API.
ebay_add_order_tracking	Add carrier/tracking information to an eBay order.
save_resale_lead	Save an arbitrage lead into the reseller pipeline.
update_resale_lead_status	Move a lead through watching, contacted, offer_made, purchased, listed, sold, or rejected.
create_inventory_item	Create a purchased item for inventory tracking.
mark_inventory_listed	Mark inventory as listed for sale.
mark_inventory_sold	Mark inventory sold and calculate realized profit.
calculate_business_metrics	Summarize leads, inventory, invested cash, sold revenue, realized profit, and ROI.
decode_vin	Validate basic VIN format/check digit and estimate model year/country offline.
calculate_vehicle_flip_profit	Calculate vehicle flip economics using eBay Motors fees and vehicle-specific costs.
score_vehicle_title_risk	Score title, VIN, lien, odometer, seller-name, and flood-market risk.
florida_dealer_threshold_status	Track Florida's three-vehicle dealer-activity presumption threshold.
find_vehicle_arbitrage_opportunities	Search vehicle leads and rank potential eBay Motors flips.
draft_ebay_motors_listing	Draft vehicle listing copy, photo checklist, and required disclosures.
save_vehicle_lead	Save a vehicle research lead.
update_vehicle_status	Update a vehicle lead status and append notes.

Sources

Source	Coverage	Requires
eBay Browse API	Official eBay item search, shipping, and detail lookups	EBAY_ACCESS_TOKEN or EBAY_APP_ID + EBAY_CERT_ID
Facebook Marketplace public search	Local used marketplace listings	location as latitude,longitude or SHOPPING_FACEBOOK_MARKETPLACE_LATITUDE/LONGITUDE; experimental
Craigslist static search HTML	Local used marketplace listings	none, configure CRAIGSLIST_SITES
OfferUp public search	Local used marketplace listings, defaulting to Miami Beach with location override support	none
Amazon public search	Amazon product search HTML parser	SHOPPING_ENABLE_AMAZON_SCRAPE=true; may be blocked
Google Shopping via SerpApi	Broad retail coverage such as Amazon, Walmart, Target, eBay, merchant sites	SERPAPI_API_KEY

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

Variable	Required	Description
EBAY_ACCESS_TOKEN	optional	Existing eBay app/user access token for Browse API search.
EBAY_APP_ID	recommended	eBay client ID for OAuth client credentials and seller OAuth.
EBAY_CERT_ID	recommended	eBay client secret for OAuth client credentials and seller OAuth.
EBAY_DEV_ID	optional	eBay dev ID, stored for account completeness.
EBAY_MARKETPLACE_ID	optional	Defaults to EBAY_US.
EBAY_USE_SANDBOX	optional	Set true for sandbox eBay APIs.
EBAY_REDIRECT_URI	required for seller OAuth	eBay OAuth redirect URI/RuName configured in the eBay Developer app.
EBAY_SELLER_REFRESH_TOKEN	optional	Single-seller refresh-token shortcut. Prefer ebay_seller_connect_url + ebay_exchange_seller_code with KV storage for production.
EBAY_SELLER_ACCESS_TOKEN	optional	Temporary seller user access token for testing seller-write calls.
SERPAPI_API_KEY	optional	Enables Google Shopping via SerpApi.
CRAIGSLIST_SITES	optional	Comma-separated Craigslist sites.
SHOPPING_FACEBOOK_MARKETPLACE_LATITUDE	optional	Default Facebook Marketplace search latitude.
SHOPPING_FACEBOOK_MARKETPLACE_LONGITUDE	optional	Default Facebook Marketplace search longitude.
SHOPPING_FACEBOOK_MARKETPLACE_RADIUS_KM	optional	Facebook Marketplace search radius. Defaults to 16.
SHOPPING_OFFERUP_DEFAULT_CITY	optional	Default OfferUp city. Defaults to Miami Beach.
SHOPPING_OFFERUP_DEFAULT_STATE	optional	Default OfferUp state. Defaults to FL.
SHOPPING_OFFERUP_DEFAULT_ZIP	optional	Default OfferUp ZIP. Defaults to 33139.
SHOPPING_OFFERUP_DEFAULT_LATITUDE	optional	Default OfferUp latitude. Defaults to 25.7907.
SHOPPING_OFFERUP_DEFAULT_LONGITUDE	optional	Default OfferUp longitude. Defaults to -80.1300.
SHOPPING_OFFERUP_RADIUS_MILES	optional	OfferUp search radius hint. Defaults to 30.
SHOPPING_ENABLE_AMAZON_SCRAPE	optional	Enables Amazon public HTML parsing.
SHOPPING_HTTP_TIMEOUT_SECONDS	optional	Request timeout. Defaults to 15.
SHOPPING_MAX_RESULTS_PER_SOURCE	optional	Default per-source search size.
SHOPPING_ESTIMATED_TAX_RATE_PERCENT	optional	Default tax estimate rate.
SHOPPING_TAX_SHIPPING	optional	Whether shipping is included in estimated tax base. Defaults to true.
SHOPPING_RESALE_STORE_PATH	optional	Local JSON path for leads and inventory. Defaults to .shopping-deals/resale-business.json.
RESALE_KV	optional	Cloudflare KV binding for hosted lead/inventory persistence.

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.