Amazon Shopping MCP Skill

Amazon Shopping MCP

Headless Chromium browser automation for Amazon.com with local DuckDB product cache and shopping list.

Server Location

/Users/alice/v/mcp/amazon-shopping/

MCP Registration

{
  "amazon-shopping": {
    "type": "stdio",
    "command": "/bin/sh",
    "args": ["-c", "cd /Users/alice/v/mcp/amazon-shopping && unset PYTHONPATH && exec uv run python -m amazon_shopping_mcp.server"]
  }
}

Stack

FastMCP 2.14.x — MCP server framework (pinned <3)
Playwright — headless Chromium for Amazon browsing
DuckDB — product cache, price history, shopping list at ~/v/amazon-shopping.duckdb
Python 3.14 via uv

Tools (12)

Browser / Amazon

| Tool | Args | Description | |------|------|-------------| | search_amazon | query, max_results=5 | Search Amazon, returns ASIN/title/price/rating | | get_product_details | asin | Full product page: features, description, availability | | add_to_cart | asin | Click Add to Cart (headless session, not logged in by default) | | view_cart | — | List cart items + subtotal | | screenshot_page | — | Screenshot to /tmp/amazon_screenshot.png | | navigate_url | url | Go to any URL, return title + 2000 char text preview |

Shopping List (DuckDB)

| Tool | Args | Description | |------|------|-------------| | list_add | asin, title, qty=1, notes="" | Add to local list | | list_view | — | Show all items with status | | list_update_status | item_id, status | Set TODO/BUY/BOUGHT/SKIP | | list_remove | item_id | Delete from list |

Price Tracking

| Tool | Args | Description | |------|------|-------------| | price_history | asin | All observed prices over time | | cached_products | query="" | Search local product cache (empty = all) |

DuckDB Schema

products (asin PK, title, price_cents, currency, rating, review_count, url, category, image_url, last_seen)
price_history (asin, price_cents, currency, observed_at)
shopping_list (id PK, asin, title, qty, notes, status, added_at)

Every search_amazon and get_product_details call auto-caches to products and appends to price_history.

Env Vars

| Var | Default | Description | |-----|---------|-------------| | AMAZON_SHOPPING_DB | ~/v/amazon-shopping.duckdb | DuckDB path |

Workflow Examples

Research + buy list

search_amazon("thunderbolt 4 cable 2m") — get top 5 results
get_product_details("B0CXRSWRBR") — read features, check availability
list_add("B0CXRSWRBR", "Cable Matters TB4 2m", qty=2) — track locally
price_history("B0CXRSWRBR") — check price trend over time

Cart operations

add_to_cart("B0CXRSWRBR") — add to Amazon cart
view_cart() — check cart subtotal
screenshot_page() — visual verification

Offline queries

cached_products("thunderbolt") — search previously seen products
list_view() — review full shopping list
price_history("B0CDH4FGZY") — price trend for Anker TB4

Limitations

Not logged in by default — cart is anonymous session. Login requires manual cookie injection or interactive auth.
Amazon anti-bot — headless Chrome may hit CAPTCHAs on heavy use. Use screenshot_page to debug.
Prices in cents — stored as integers (2999 = $29.99) to avoid float rounding.
Single browser context — tools share one Chromium page. Concurrent calls may race.

Development

cd /Users/alice/v/mcp/amazon-shopping
unset PYTHONPATH
uv sync                              # install deps
uv run playwright install chromium   # install browser (once)
uv run python -m amazon_shopping_mcp.server  # run server

Companion Artifact

Shopping list org file: ~/v/amazon-shopping.org — manually curated product research with ASINs, prices, and notes.

Agent Skills: Amazon Shopping MCP

Install this agent skill to your local

Skill Files