Amazon Order History CSV Download MCP

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

# Clone the repository
git clone https://github.com/marcusquinn/amazon-order-history-csv-download-mcp.git
cd amazon-order-history-csv-download-mcp

# Install dependencies
npm install

# Build
npm run build

# Install Playwright browsers
npx playwright install chromium

Configuration

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

{
  "mcpServers": {
    "amazon-orders": {
      "command": "node",
      "args": ["/path/to/amazon-order-history-csv-download-mcp/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 |

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.

{
  "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.

{
  "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.

{
  "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

# 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 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

# 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 for detailed architecture documentation.

Related Projects

• QuickFile MCP - MCP server for QuickFile UK accounting software. Use Amazon order exports with QuickFile for expense tracking and VAT reconciliation.
• OpenCode - Open-source AI coding assistant with MCP support
• QuickFile - UK accounting software
• QuickFile API - QuickFile API documentation
• Model Context Protocol - Protocol specification for AI tool integration
• AI DevOps Framework - Comprehensive AI infrastructure management

Credits

This project was inspired by 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 for full acknowledgments.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please read AGENTS.md for development guidelines.