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 resultsget_product_details("B0CXRSWRBR") — read features, check availabilitylist_add("B0CXRSWRBR", "Cable Matters TB4 2m", qty=2) — track locallyprice_history("B0CXRSWRBR") — check price trend over time
Cart operations
add_to_cart("B0CXRSWRBR") — add to Amazon cartview_cart() — check cart subtotalscreenshot_page() — visual verification
Offline queries
cached_products("thunderbolt") — search previously seen productslist_view() — review full shopping listprice_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.
plurigrid