MCP Amazon - Order Analytics Server

An MCP (Model Context Protocol) server that connects to Amazon through the DAX API to extract and analyze your order data. Get insights into your spending patterns, filter orders, and export data for further analysis.

🚀 Quick Start

Prerequisites

• Node.js 18+
• DAX API server access (defaults to https://api.getgather.studio)
• Amazon account credentials

Installation

# Clone the repository
git clone <repository-url>
cd mcp-amazon

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Create a .env file (copy from .env.example):

# DAX API Configuration
DAX_API_URL=https://api.getgather.studio
DAX_API_KEY=
DAX_PLATFORM=local-bundle
DAX_BROWSER=chromium
DAX_FRAMEWORK=patchright

# Location Configuration (US states supported)
DAX_COUNTRY=US
DAX_STATE=Ohio

# Cache Configuration
CACHE_DIR=~/.mcp-amazon

🔧 Available Tools

Authentication & Session Management

• amazon_authenticate - Start Amazon authentication with DAX API
• amazon_continue_auth - Provide credentials (email, password, OTP)
• amazon_select_choice - Select from authentication choices (multi-step flows)
• amazon_close_session - Clean up DAX session

Order Data Operations

• amazon_get_cached_orders - Retrieve locally cached order data (auto-populated after authentication)

Filtering & Search

• amazon_filter_orders - Filter by date range, price, categories, sellers
• amazon_search_orders - Search orders by keywords

Analytics & Insights

• amazon_analyze_spending - Generate comprehensive spending analytics
• amazon_export_orders - Export data to CSV/JSON formats

📊 Available Resources

• amazon://orders - Access cached order data
• amazon://analytics - Real-time analytics summaries
• amazon://session-info - Current authentication status

💬 Available Prompts

• analyze_spending_patterns - Analyze spending patterns and trends
  • Arguments: time_period, focus_area
• budget_recommendations - Generate budget recommendations
  • Arguments: target_reduction, exclude_categories
• find_expensive_purchases - Identify expensive or unusual purchases
  • Arguments: threshold, category_filter
• compare_sellers - Compare spending across different sellers
  • Arguments: top_n
• seasonal_analysis - Analyze seasonal spending patterns
  • Arguments: year

💡 Usage Examples

Basic Authentication Flow

// 1. Start authentication (uses environment defaults)
amazon_authenticate({ state: "California" })

// 2. Start with custom platform/browser (overrides environment)
amazon_authenticate({
  state: "California",
  platform: "hyperbrowser",
  browser: "chromium",
  framework: "patchright"
})

// 3. Provide credentials when prompted
amazon_continue_auth({
  email: "[email protected]",
  password: "yourpassword"
})

// 4. Handle multi-choice scenarios (2FA/OTP options)
// If response shows status: "NEED_CHOICE", use amazon_select_choice
amazon_select_choice({
  choice_name: "OTP Current Modality Choice",
  inputs: { otp: "123456" }
})

// 5. Alternative: Provide OTP directly if no choices
amazon_continue_auth({ otp: "123456" })

Order Analysis

// Orders are automatically extracted and cached during authentication!
// Just complete the auth flow, then use the cached data:

// Filter orders by date and price
amazon_filter_orders({
  start_date: "2024-01-01",
  end_date: "2024-12-31",
  min_amount: 50
})

// Generate spending analytics
amazon_analyze_spending()

// Export to CSV
amazon_export_orders({ format: "csv" })

Search & Insights

// Search for specific products
amazon_search_orders({ query: "laptop" })

// Get cached orders
amazon_get_cached_orders()

🌍 Supported Locations

US States: All 50 US states plus Washington DC are supported for browser location. Use full state names like "California", "New York", etc.

🔒 Security & Privacy

• Local Processing: All order data is processed and cached locally
• No Data Transmission: Your order data never leaves your machine
• Secure Sessions: DAX API handles authentication securely
• Cache Encryption: Local cache files are stored in your home directory

🛠️ Configuration Options

Environment Variables

| Variable | Description | Default | Options | |----------|-------------|---------|---------| | DAX_API_URL | DAX API server URL | https://api.getgather.studio | Any valid URL | | DAX_API_KEY | DAX API authentication key | Empty (no auth) | Bearer token for deployed DAX | | DAX_PLATFORM | Browser platform | local-bundle | See Platform Options | | DAX_BROWSER | Browser type | chromium | chromium, firefox, webkit | | DAX_FRAMEWORK | Automation framework | patchright | patchright, playwright, rebrowser | | DAX_STATE | US state for browser location | Ohio | Any US state name | | CACHE_DIR | Local cache directory | ~/.mcp-amazon | Any valid directory path |

Platform Options

local-bundle (Recommended for Development)

• ✅ Best for: Local development and testing
• ✅ Features: Persistent browser profiles, all browsers supported
• ✅ Performance: Fast startup, local execution
• ❌ Limitations: May be detected by anti-bot systems

hyperbrowser (Recommended for Production)

• ✅ Best for: Production use with anti-bot protection
• ✅ Features: Cloud-based, stealth mode, captcha solving
• ✅ Performance: High success rate on protected sites
• ❌ Limitations: Requires API key setup in DAX, Chromium only, slower startup
• 🔑 Setup: Configure HYPERBROWSER_API_KEY in your DAX server environment

browserbase (Alternative Cloud Option)

• ✅ Best for: Scalable production deployment
• ✅ Features: Cloud-based, persistent contexts, proxy support
• ✅ Performance: Good for enterprise use cases
• ❌ Limitations: Requires API key setup in DAX, Chromium only
• 🔑 Setup: Configure BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID in your DAX server environment

local-ws (Advanced)

• ✅ Best for: Debugging with existing browser
• ✅ Features: Connect to running Chrome instance
• ❌ Limitations: macOS only, Chromium only, complex setup

Framework Recommendations

• patchright (Default) - Best anti-detection, recommended for production
• playwright - Standard option, good for development
• rebrowser - Alternative anti-detection when patchright fails

Browser Recommendations

• chromium (Default) - Most compatible, best feature support
• firefox - Good alternative when Chromium is detected
• webkit - Rarely used, limited platform support

Configuration Examples

Development Setup:

DAX_PLATFORM=local-bundle
DAX_BROWSER=chromium
DAX_FRAMEWORK=patchright

Production Setup (Anti-Bot Sites):

DAX_PLATFORM=hyperbrowser
DAX_BROWSER=chromium
DAX_FRAMEWORK=patchright
# Note: Configure HYPERBROWSER_API_KEY in DAX server environment

Alternative for Chromium Detection:

DAX_PLATFORM=local-bundle
DAX_BROWSER=firefox
DAX_FRAMEWORK=patchright

📈 Analytics Features

Spending Analytics:

• Total spending and order counts
• Monthly/yearly spending trends
• Category-wise spending breakdown
• Top sellers and vendors
• Average order values
• Recent order activity

Export Formats:

• JSON for programmatic access
• CSV for spreadsheet analysis
• Filtered exports based on search criteria

🚨 Troubleshooting

Common Issues

"DAX API is not available"

• Ensure DAX server is running: cd ../dax && python -m apps.api.src.api.main
• Check DAX_API_URL configuration

"Not authenticated" / "Unauthorized" (401 Error)

• Set DAX_API_KEY environment variable with your DAX API key
• For deployed DAX servers, contact admin for API key
• Local DAX: Set API_KEYS='["your-key-here"]' in DAX server environment
• Test with health endpoint: curl http://your-dax-url/health (no auth required)

"No active session"

• Complete authentication flow first with amazon_authenticate
• Check session status with amazon://session-info resource

"Authentication failed"

• Verify Amazon credentials
• Check for 2FA/OTP requirements
• Ensure account is accessible from selected location

Cache Issues

• Clear cache: Delete ~/.mcp-amazon/orders.json
• Check cache status: Use amazon_get_cached_orders

🏗️ Integration Examples

Cursor Editor

Option 1: Wrapper Script (recommended for compatibility)

{
  "mcpServers": {
    "amazon-orders": {
      "command": "node",
      "args": ["mcp-amazon-server.js"],
      "cwd": "/path/to/mcp-amazon"
    }
  }
}

Option 2: Built Version (requires npm run build first)

{
  "mcpServers": {
    "amazon-orders": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/mcp-amazon"
    }
  }
}

Option 3: Development Mode (no build needed)

{
  "mcpServers": {
    "amazon-orders": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/mcp-amazon",
      "env": {
        "DAX_API_URL": "https://api.getgather.studio",
        "DAX_API_KEY": "",
        "DAX_PLATFORM": "local-bundle",
        "DAX_BROWSER": "chromium",
        "DAX_FRAMEWORK": "patchright",
        "DAX_COUNTRY": "US",
        "DAX_STATE": "Ohio",
        "CACHE_DIR": "~/.mcp-amazon"
      }
    }
  }
}

Note:

• The wrapper script (Option 1) ensures proper working directory and environment setup for Cursor integration
• Replace /path/to/mcp-amazon with the absolute path to your cloned repository

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! See DEVELOPMENT.md for development setup and guidelines.

Need Help?

• Check the troubleshooting section
• Review DAX API documentation
• Open an issue on GitHub