Amazon Lyr

amazon-lyr

The full Amazon lifecycle as MCP tools for AI agents — research products and reviews, manage the cart, place orders, track shipments, start returns — all through your own logged-in browser session. No PA-API keys.

An agent session, start to finish

This is one real conversation with an agent running amazon-lyr — no steps hidden:

1. search_products("noise cancelling headphones", max_price=300, min_rating=4)
2. review_insights("B0X1234567")            # star spread + keyword themes
3. search_in_reviews("B0X1234567", query="broke")     # what actually breaks?
4. add_to_cart("B0X1234567", quantity=1)
5. checkout_preview()                        # totals + address + payment, nothing bought
6. place_order(confirm="PLACE_ORDER")       # only after the user said "buy it"
   ✓ order placed · #111-2223334-5556667
7. track_shipment("111-2223334-5556667")
8. initiate_return("111-2223334-5556667", reason="defective", asin_hint="…")
9. list_returns()                           # refund status confirmed

Every step is a typed MCP tool call. The buying step is deliberately hard to fire by accident — see Safety model.

Why it's different

How it works

browser cookies ──▶ AmazonClient (curl_cffi, captcha-aware)
                        │
                        ▼
              bs4 parsers ──▶ normalized dicts ──▶ 21 FastMCP tools
                                                   (readOnly / destructive annotations)

Auth is your own session: amazon-lyr login imports cookies from Chrome, Brave, Firefox, Edge or Zen via obscura-core, or from an explicit JSON export. Reads need the login token; cart, orders, returns and checkout also need the session context cookies.

Install

# Persistent install — uv tool (isolated; bootstraps uv on clean systems)
curl -sSL https://raw.githubusercontent.com/ishan-parihar/amazon-lyr/main/install.sh | bash

# Zero-install run without persistence:
uvx --from git+https://github.com/ishan-parihar/amazon-lyr amazon-lyr --version

Then authenticate once and serve:

amazon-lyr login --browser chrome            # or: --cookies-file cookies.json
amazon-lyr search "mechanical keyboard"      # shell works immediately
amazon-lyr serve                             # MCP server (stdio)

{
  "mcpServers": {
    "amazon": {
      "command": "amazon-lyr",
      "args": ["serve"]
    }
  }
}

Tools (21)

Safety model

Money moves through exactly two gates:

1. Session gate — every mutation requires full login cookies (at-main + session-id/ubid-main). Reads-only sessions are refused before any request is made.
2. Consent gate — place_order refuses to run unless passed the exact literal confirm="PLACE_ORDER". The intended flow is: preview for the user → user approves → then pass the literal. cancel_order and initiate_return are similarly annotated as destructive/non-idempotent so agent frameworks treat them accordingly.

Card verification (OTP / 3-D Secure) is detected mid-checkout and reported as needs_verification with browser instructions — never guessed through.

Limits

Honest ceilings, all surfaced as typed errors instead of wrong data:

• CAPTCHA walls — account-area pages are stricter than the catalog; re-import fresh cookies or wait it out (CaptchaError includes hints)
• Soft throttles — sub-3-second cadences get silent empty grids; responses carry possibly_throttled: true when suspected
• Geo price variants — some variants render prices client-side; search falls back to text-scanning, get_product stays authoritative
• No auto-buy without consent — by design; checkout demands the explicit confirm literal and user approval

Development

git clone https://github.com/ishan-parihar/amazon-lyr && cd amazon-lyr
uv sync --extra dev
uv run ruff check . && uv run pytest -q

Architecture notes, invariants, and the release process live in AGENTS.md.

License

MIT © Ishan Parihar