# @striderlabs/mcp-amazon

[![npm version](https://badge.fury.io/js/%40striderlabs%2Fmcp-amazon.svg)](https://www.npmjs.com/package/@striderlabs/mcp-amazon)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Amazon MCP Server** by [Strider Labs](https://striderlabs.ai) — give AI agents the ability to search products, manage your cart, place orders, and track shipments on Amazon via browser automation.

## Features

- **Product Search** — search Amazon with full result details (ASIN, price, ratings, Prime badge)
- **Product Details** — fetch complete product info by ASIN or URL
- **Cart Management** — add items, view cart, clear cart
- **Order Placement** — preview and place orders with dual-confirmation safety
- **Order Tracking** — track shipments with status and carrier info
- **Order History** — retrieve past orders
- **Prime Status** — check Prime membership and benefits
- **Address Management** — set delivery address
- **Session Persistence** — cookies saved to `~/.strider/amazon/` across sessions
- **Stealth Mode** — random delays, user agent rotation, webdriver masking to reduce bot detection

## Installation

```bash
npm install -g @striderlabs/mcp-amazon

# Install Playwright browsers (required)
npx playwright install chromium
```

## MCP Client Configuration

### Claude Desktop (`~/.claude/claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "amazon": {
      "command": "striderlabs-mcp-amazon"
    }
  }
}
```

### Generic MCP Client

```json
{
  "mcpServers": {
    "amazon": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-amazon"]
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `amazon_status` | Check login status and session info |
| `amazon_login` | Initiate login flow (returns URL + instructions) |
| `amazon_logout` | Clear session and cookies |
| `amazon_search` | Search products by keyword |
| `amazon_get_product` | Get product details by ASIN or URL |
| `amazon_add_to_cart` | Add product to cart (ASIN, URL, or query) |
| `amazon_view_cart` | View cart contents and subtotal |
| `amazon_clear_cart` | Remove all items from cart |
| `amazon_preview_order` | Preview order before placing |
| `amazon_place_order` | Place order (requires `confirm=true`) |
| `amazon_track_order` | Track order by ID |
| `amazon_get_orders` | Get order history |
| `amazon_prime_check` | Check Prime membership status |
| `amazon_set_address` | Set delivery address |

## Usage Examples

### Search and add to cart

```
Search for "AirPods Pro" on Amazon
→ amazon_search({ query: "AirPods Pro", maxResults: 5 })

Add the first result to cart
→ amazon_add_to_cart({ asinOrQuery: "B0BDHWDR12", quantity: 1 })
```

### Place an order

```
Preview my order before placing
→ amazon_preview_order()

Place the order (user must confirm first)
→ amazon_place_order({ confirm: true })
```

### Track a shipment

```
Track order 123-4567890-1234567
→ amazon_track_order({ orderId: "123-4567890-1234567" })
```

## Authentication Flow

Amazon requires manual login (headless browsers cannot complete Amazon's full auth flow including 2FA):

1. Run `amazon_login` — it returns `https://www.amazon.com/ap/signin`
2. Open that URL in your browser and log in with your Amazon credentials
3. Complete any 2-factor authentication
4. Run `amazon_status` to verify the session is detected
5. Cookies are saved to `~/.strider/amazon/cookies.json` for future sessions

## Configuration

Session data is stored in:

```
~/.strider/amazon/
├── cookies.json    # Browser session cookies
└── session.json    # Cached session metadata
```

To reset: run `amazon_logout` or delete the `~/.strider/amazon/` directory.

## Order Safety

`amazon_place_order` requires `confirm: true` to actually place an order:

- Without `confirm: true` — returns a preview (same as `amazon_preview_order`)
- With `confirm: true` — places the order **immediately**

**Never set `confirm: true` without explicit user consent.**

## Bot Detection

Amazon has aggressive bot detection. This server includes:

- Random delays between actions (500–2000ms)
- User agent rotation (Chrome/Safari on macOS/Windows)
- Webdriver property masking
- Browser plugin/language spoofing
- Proper viewport and screen resolution

**If you receive a CAPTCHA error:** visit `amazon.com` in your regular browser, complete the CAPTCHA, then retry. Cookies will be re-used in subsequent calls.

## Technical Details

- **Runtime:** Node.js 18+, ES modules
- **Browser:** Playwright Chromium (headless)
- **Transport:** MCP stdio
- **Session storage:** `~/.strider/amazon/`

## Limitations

- Requires manual login (no programmatic auth for Amazon)
- CAPTCHA challenges must be completed in a real browser
- Payment method must be pre-configured on your Amazon account
- Amazon's UI changes may break DOM selectors — report issues on GitHub
- Not affiliated with Amazon.com, Inc.

## Troubleshooting

**"CAPTCHA detected"**
Visit amazon.com in your browser, complete the CAPTCHA, then retry.

**"Not logged in"**
Run `amazon_login`, open the URL, log in, then run `amazon_status`.

**"Add to Cart button not found"**
The item may be sold by a third-party seller requiring seller selection, or it may be unavailable. Try `amazon_get_product` first to verify availability.

**"Page load timed out"**
Check your internet connection. Amazon pages can be slow on first load.

## Development

```bash
git clone https://github.com/striderlabs/mcp-amazon
cd mcp-amazon
npm install
npx playwright install chromium
npm run build
npm start
```

## License

MIT — see [LICENSE](LICENSE)

---

Built by [Strider Labs](https://striderlabs.ai)