Amazon Order History Csv Download MCP

🚀 Amazon Order History CSV Download MCP

This project is an MCP (Model Context Protocol) server that enables users to download Amazon order history as CSV files. It supports the export of orders, items, shipments, and transactions across 16 Amazon regional sites, offering a comprehensive solution for managing Amazon order data.

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

✨ 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

💻 Usage Examples

🔍 Supported Regions

📄 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.

📦 Items (export_amazon_items_csv)

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

📦 Shipments (export_amazon_shipments_csv)

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

⚠️ Important 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.

🎁 Gift Cards (export_amazon_gift_cards_csv)

Gift card activity and balance history.

🛠️ Additional Tools

🛠️ Query Tools

🛠️ 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

💡 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.