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.
- 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
# 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 chromiumAdd 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"]
}
}
}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"
| 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 |
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 |
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 |
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.
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 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 |
| 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 |
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"
}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
Verify if the browser session is authenticated before running exports.
{
"region": "uk"
}Returns authentication status, username if logged in, or login URL if not.
When exporting large order histories (100+ orders), the extraction process can take several minutes. MCP clients typically have timeout limits that may need adjustment.
| Orders | Estimated Time |
|---|---|
| 10 | ~15 seconds |
| 50 | ~1.5 minutes |
| 100 | ~3 minutes |
| 500 | ~15 minutes |
- Use
max_ordersparameter to limit extraction scope - Export by year rather than entire history
- Configure client timeouts if needed (see below)
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:
- Use smaller batches with
max_orders - Configure your MCP client's
maxTotalTimeoutsetting (if available) - The server sends progress notifications which can reset timeouts if
resetTimeoutOnProgressis enabled in your client
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.
# Run in development mode
npm run dev
# Run tests
npm test
# Type checking
npm run typecheck
# Linting
npm run lintFor 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
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector
# Run inspector with this server
npx @modelcontextprotocol/inspector node dist/index.jsThen open http://localhost:5173 in your browser to:
- See all available tools listed
- Click a tool to view its schema
- Fill in parameters and execute
- View the raw JSON response
- Test authentication: Call
check_amazon_auth_statuswith{"region": "uk"} - Test order fetch: Call
get_amazon_orderswith a small date range - Test order details: Call
get_amazon_order_detailswith a known order ID - Test exports: Call any
export_amazon_*_csvtool
This is the recommended approach for:
- Debugging extraction issues
- Verifying new features work correctly
- Testing region-specific behavior
- Investigating error responses
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.
- 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
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.
MIT License - see LICENSE for details.
Contributions welcome! Please read AGENTS.md for development guidelines.