# Amazon Order History CSV Download MCP

[![GitHub Actions](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp/workflows/Code%20Quality/badge.svg)](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/Version-0.4.3-blue)](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp/releases)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![AGENTS.md](https://img.shields.io/badge/AGENTS.md-Compliant-blue.svg)](https://agents.md/)

MCP (Model Context Protocol) server for downloading Amazon order history as CSV files.
Supports orders, items, shipments, and transactions export across 16 Amazon regional sites.

## Features

- **4 Export Types**: Orders summary, item details, shipment tracking, payment transactions
- **16 Amazon Regions**: US, UK, Canada, Germany, France, Spain, Italy, and more
- **Browser Automation**: Uses Playwright for reliable data extraction
- **AI Assistant Integration**: Works with Claude, GPT, and other MCP-compatible assistants
- **Flexible Date Ranges**: Export by year, date range, or recent months

## Quick Start

### Installation

Install the MCP server globally from npm, then install Chromium for Playwright:

```bash
npm install --global amz-order-history-csv-mcp
npx playwright install chromium
```

You can also run the server without a global installation:

```bash
npx --yes playwright install chromium
npx --yes amz-order-history-csv-mcp
```

Node.js 18 or newer is required.

For source development, clone the repository and build it locally:

```bash
git clone https://github.com/marcusquinn/amazon-order-history-csv-download-mcp.git
cd amazon-order-history-csv-download-mcp
npm ci
npm run build
npx playwright install chromium
```

### Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "amazon-orders": {
      "command": "npx",
      "args": ["--yes", "amz-order-history-csv-mcp"]
    }
  }
}
```

Source checkouts can instead use `node` with the absolute path to
`dist/index.js`.

### Usage

Once configured, you can ask your AI assistant:

- "Download my Amazon orders from 2024 as CSV"
- "Export all items I purchased on Amazon UK this year"
- "Get shipment tracking for my recent Amazon orders"
- "Export my Amazon payment transactions for tax purposes"
- "What's my Amazon gift card balance?"
- "Show me all my Amazon transactions from last month"

## Supported Regions

| Region         | Domain        | Currency |
| -------------- | ------------- | -------- |
| United States  | amazon.com    | USD      |
| United Kingdom | amazon.co.uk  | GBP      |
| Canada         | amazon.ca     | CAD      |
| Germany        | amazon.de     | EUR      |
| France         | amazon.fr     | EUR      |
| Spain          | amazon.es     | EUR      |
| Italy          | amazon.it     | EUR      |
| Netherlands    | amazon.nl     | EUR      |
| Japan          | amazon.co.jp  | JPY      |
| Australia      | amazon.com.au | AUD      |
| Mexico         | amazon.com.mx | MXN      |
| India          | amazon.in     | INR      |
| UAE            | amazon.ae     | AED      |
| Saudi Arabia   | amazon.sa     | SAR      |
| Ireland        | amazon.ie     | EUR      |
| Belgium        | amazon.com.be | EUR      |

## Export Types

### Orders (`export_amazon_orders_csv`)

Fast order summary from the order list page (~0.5s per 10 orders). Best for browsing and basic reporting.

| Column           | Description                                   |
| ---------------- | --------------------------------------------- |
| Order ID         | Amazon order identifier (XXX-XXXXXXX-XXXXXXX) |
| Order Date       | Date order was placed (YYYY-MM-DD)            |
| Total            | Order total amount                            |
| Status           | Delivery status (Delivered, Shipped, etc.)    |
| Items            | Number of items in order                      |
| Address Line 1-7 | Shipping address (up to 7 lines)              |
| Subscribe & Save | Subscription frequency if applicable          |
| Platform         | Always "amazon"                               |
| Region           | Amazon region code (us, uk, de, etc.)         |
| Order URL        | Link to order details page                    |

### Items (`export_amazon_items_csv`)

Detailed item-level export with full order context (~2s per order). Best for expense tracking and accounting.

| Column            | Description                        |
| ----------------- | ---------------------------------- |
| Order ID          | Parent order identifier            |
| Order Date        | Date order was placed              |
| ASIN              | Amazon product identifier          |
| Product Name      | Full product title                 |
| Condition         | New, Used, etc.                    |
| Quantity          | Number of units                    |
| Unit Price        | Price per item                     |
| Item Total        | Quantity × Unit Price              |
| Seller            | Seller/merchant name               |
| Subscribe & Save  | Subscription frequency             |
| Order Subtotal    | Pre-tax/shipping subtotal          |
| Order Shipping    | Shipping cost                      |
| Order Tax         | Sales tax amount                   |
| Order VAT         | VAT amount (UK/EU)                 |
| Order Promotion   | Discount amount                    |
| Order Total       | Final order total                  |
| Order Grand Total | Including all fees                 |
| Order Status      | Delivery status                    |
| Recipient         | Ship-to name                       |
| Address Line 1-7  | Full shipping address              |
| Payment Method    | Card type (Visa, Mastercard, etc.) |
| Card Last 4       | Last 4 digits of card              |
| Product URL       | Link to product page               |
| Image URL         | Product image URL                  |
| Order URL         | Link to order details              |
| Region            | Amazon region code                 |

### Shipments (`export_amazon_shipments_csv`)

Shipment and tracking information (~4s per order, +2s with `fetch_tracking_numbers`). Best for delivery tracking.

| Column            | Description                                |
| ----------------- | ------------------------------------------ |
| Order ID          | Parent order identifier                    |
| Order Date        | Date order was placed                      |
| Shipment ID       | Unique shipment identifier                 |
| Status            | Shipment status text                       |
| Delivered         | Yes/No/Unknown                             |
| Tracking ID       | Carrier tracking number                    |
| Carrier           | Carrier name (Royal Mail, DPD, etc.)       |
| Tracking URL      | Link to carrier tracking                   |
| Items in Shipment | Number of items                            |
| Item Names        | List of product names                      |
| Payment Amount    | Amount charged (falls back to order total) |
| Refund            | Refund amount if any                       |
| Region            | Amazon region code                         |

**Note**: Set `fetch_tracking_numbers: true` to visit ship-track pages and extract actual carrier tracking IDs (e.g., "AZ218181365JE") and carrier names. Without this option, only Amazon's internal tracking URLs are captured.

### Transactions (`export_amazon_transactions_csv`)

Payment transaction details for financial reconciliation.

| Column           | Description         |
| ---------------- | ------------------- |
| Transaction Date | Date of charge      |
| Order ID(s)      | Associated order(s) |
| Payment Method   | Card/payment type   |
| Card Info        | Last 4 digits       |
| Amount           | Transaction amount  |
| Currency         | Currency code       |

### Gift Cards (`export_amazon_gift_cards_csv`)

Gift card activity and balance history.

| Column          | Description               |
| --------------- | ------------------------- |
| Date            | Transaction date          |
| Description     | Activity description      |
| Type            | added/applied/refund      |
| Amount          | Transaction amount        |
| Closing Balance | Balance after transaction |
| Order ID        | Associated order if any   |
| Claim Code      | Gift card claim code      |
| Serial Number   | Gift card serial number   |
| Currency        | Currency code             |
| Region          | Amazon region code        |

## Additional Tools

### Query Tools

| Tool                                | Description                                   |
| ----------------------------------- | --------------------------------------------- |
| `get_amazon_orders`                 | Fetch orders with optional items/shipments    |
| `get_amazon_order_details`          | Get full details for a specific order         |
| `get_amazon_transactions`           | Fetch all transactions from transactions page |
| `get_amazon_gift_card_balance`      | Get current balance and history               |
| `get_amazon_gift_card_transactions` | Get detailed gift card activity               |
| `check_amazon_auth_status`          | Check if browser is logged in                 |

### Invoice PDF download (`download_amazon_invoice`)

Downloads an A4 PDF for one authenticated order after confirming that the print
page contains both the requested order ID and invoice-specific content.

```json
{
  "order_id": "123-4567890-1234567",
  "region": "uk",
  "output_path": "/absolute/path/to/invoice.pdf"
}
```

`output_path` is optional and must be absolute when supplied. The default is
`~/Downloads/amazon-{region}-invoice-{order_id}.pdf`; its parent directory is
created when needed. A successful response reports the saved `path` and exact
`bytes`. Authentication redirects, Amazon error pages, mismatched invoice
identity, rendering failures, and write failures return an MCP error without
publishing a partial PDF or replacing a prior file.

### Transactions Page (`get_amazon_transactions`)

Extracts ALL payment transactions from Amazon's dedicated transactions page (`/cpe/yourpayments/transactions`). Much faster than extracting from individual order pages.

```json
{
  "region": "us",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}
```

### Gift Card Balance (`get_amazon_gift_card_balance`)

Gets your current Amazon gift card balance and recent activity from `/gc/balance`.

```json
{
  "region": "us"
}
```

Returns:

- Current balance
- Recent gift card activity (credits/debits)
- Associated order IDs

### Authentication Check (`check_amazon_auth_status`)

Verify if the browser session is authenticated before running exports.

```json
{
  "region": "uk"
}
```

Returns authentication status, username if logged in, or login URL if not.

## Timeouts & Large Order Histories

When exporting large order histories (100+ orders), the extraction process can take several minutes. MCP clients typically have timeout limits that may need adjustment.

### Estimated Processing Times

| Orders | Estimated Time |
| ------ | -------------- |
| 10     | ~15 seconds    |
| 50     | ~1.5 minutes   |
| 100    | ~3 minutes     |
| 500    | ~15 minutes    |

### Recommendations

1. **Use `max_orders` parameter** to limit extraction scope
2. **Export by year** rather than entire history
3. **Configure client timeouts** if needed (see below)

### Client Timeout Configuration

For OpenCode/Claude Desktop, the timeout is typically set in the MCP client configuration. If you see `MCP error -32001: Maximum total timeout exceeded`, you may need to:

1. Use smaller batches with `max_orders`
2. Configure your MCP client's `maxTotalTimeout` setting (if available)
3. The server sends progress notifications which can reset timeouts if `resetTimeoutOnProgress` is enabled in your client

### Progress Notifications

The server sends progress notifications during extraction:

- `Order X/Y (order-id) - ETA: ~Xm Xs`

These help track progress and can reset client timeouts if configured.

## Development

```bash
# Run in development mode
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint
```

### Testing with MCP Inspector

For development and debugging, use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool instead of running through an AI assistant. This provides:

- **Direct tool invocation** - Call MCP tools directly with custom parameters
- **Real-time response viewing** - See full JSON responses without AI interpretation
- **Faster iteration** - No waiting for AI to process requests
- **Debug visibility** - View raw server output and errors

#### Quick Start

```bash
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run inspector with this server
npx @modelcontextprotocol/inspector node dist/index.js
```

Then open `http://localhost:5173` in your browser to:

1. See all available tools listed
2. Click a tool to view its schema
3. Fill in parameters and execute
4. View the raw JSON response

#### Example Test Workflow

1. **Test authentication**: Call `check_amazon_auth_status` with `{"region": "uk"}`
2. **Test order fetch**: Call `get_amazon_orders` with a small date range
3. **Test order details**: Call `get_amazon_order_details` with a known order ID
4. **Test exports**: Call any `export_amazon_*_csv` tool

This is the recommended approach for:

- Debugging extraction issues
- Verifying new features work correctly
- Testing region-specific behavior
- Investigating error responses

## Architecture

This project uses a plugin architecture designed for extensibility:

- **Core Framework**: Shared utilities for CSV, dates, currencies, browser automation
- **Platform Plugins**: Amazon-specific extraction logic (future: eBay, AliExpress, etc.)

See [AGENTS.md](AGENTS.md) for detailed architecture documentation.

## Related Projects

- **[QuickFile MCP](https://github.com/marcusquinn/quickfile-mcp)** - MCP server for QuickFile UK accounting software. Use Amazon order exports with QuickFile for expense tracking and VAT reconciliation.
- **[OpenCode](https://opencode.ai)** - Open-source AI coding assistant with MCP support
- **[QuickFile](https://www.quickfile.co.uk/)** - UK accounting software
- **[QuickFile API](https://api.quickfile.co.uk/)** - QuickFile API documentation
- **[Model Context Protocol](https://modelcontextprotocol.io)** - Protocol specification for AI tool integration
- **[AI DevOps Framework](https://github.com/marcusquinn/aidevops)** - Comprehensive AI infrastructure management

## Credits

This project was inspired by [AZAD](https://github.com/philipmulcahy/azad), a Chrome
extension for Amazon order history export. This is an original implementation built
as an MCP server - not a fork or derivative work.

See [CREDITS.md](CREDITS.md) for full acknowledgments.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please read [AGENTS.md](AGENTS.md) for development guidelines.