amazon-mcp-local

Amazon Cart MCP Server

GitHub Website

Local MCP (Model Context Protocol) server that enables AI assistants like Poke to interact with your personal Amazon cart through browser automation. Uses Puppeteer for browser control, exposed securely via ngrok.

⚠️ Important Disclaimer

This tool uses browser automation to interact with Amazon.com.

By using this software, you acknowledge and accept these risks.

Features

Quick Start

Prerequisites

Installation

  1. Clone the repository: 
    git clone https://github.com/meimakes/amazon-mcp-local.git
cd amazon-mcp-local
  2. Install dependencies: 
    npm install
  3. Configure environment: 
    cp .env .env.local  # Optional: keep your settings separate

    Edit .env and set:

    • AUTH_TOKEN - Generate a secure random token (required)
    • HEADLESS=false - For first-time login
    • AMAZON_DOMAIN=amazon.com - Or your local Amazon domain
  4. Build the project: 
    npm run build
  5. Start the server: 
    npm start
  6. First-time login:
    • A Chrome browser window will open
    • Log into your Amazon account manually
    • Session will be saved in ./user-data/
    • After logging in once, you can:
      • Stop the server (Ctrl+C)
      • Set HEADLESS=true in .env
      • Restart with headless mode
  7. Expose via ngrok (in a separate terminal): 
    npm run tunnel
# Note the HTTPS URL (e.g., https://abc123.ngrok.io)

Connecting to Poke

  1. Copy your ngrok URL from the terminal
  2. In Poke, add a custom MCP integration:
    • URL: https://your-ngrok-url.ngrok.io/sse
    • API Key: Your AUTH_TOKEN from .env
    • Type: MCP Server

  3. Important: Always use the /sse endpoint!

  4. Test the connection by asking Poke:
    • “What tools do you have?”
    • “Search Amazon for wireless mouse”

Available Tools

Tool Description Parameters
search_amazon Search for products on Amazon query (required)
add_to_cart Add a product to cart query or asin, quantity (optional)
view_cart View current cart contents None
check_login Verify Amazon login status None

Architecture

┌─────────────────┐
│   Poke.com      │ (Remote AI Assistant)
│   (Cloud)       │
└────────┬────────┘
         │ HTTPS
         ↓
┌─────────────────┐
│     ngrok       │ (Secure Tunnel)
│  Public HTTPS   │
└────────┬────────┘
         │ Local
         ↓
┌─────────────────┐
│   MCP Server    │ (Port 3000)
│   SSE + HTTP    │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   Puppeteer     │ (Browser Automation)
│  + Chrome       │
│  (Persistent    │
│   Session)      │
└─────────────────┘

Configuration

Environment Variables

Variable Default Description
PORT 3000 Server port
AUTH_TOKEN required Bearer token for authentication
AMAZON_DOMAIN amazon.com Amazon domain (e.g., amazon.co.uk)
HEADLESS false Run browser in headless mode
USER_DATA_DIR ./user-data Chrome user data directory

Example .env

PORT=3000
AUTH_TOKEN=a1b2c3d4-e5f6-4789-a012-3b4c5d6e7f8a
AMAZON_DOMAIN=amazon.com
HEADLESS=false
USER_DATA_DIR=./user-data

Security

⚠️ Important Security Considerations

  1. AUTH_TOKEN Protection
    • Never commit .env to Git (already in .gitignore)
    • Use a cryptographically secure random token
    • Generate with: openssl rand -hex 32
  2. ngrok Security
    • Free tier URLs are public but unguessable
    • Consider ngrok’s authentication features for extra security
    • Upgrade to ngrok paid plan for reserved domains and IP restrictions
  3. Session Data
    • Login sessions stored in ./user-data/
    • Contains cookies and authentication tokens
    • Never share or commit this directory
    • Already excluded via .gitignore
  4. Network Security
    • Server only accepts authenticated requests
    • All traffic through ngrok is HTTPS encrypted
    • Local server binds to localhost only
  5. Browser Automation
    • Puppeteer runs with sandbox disabled (required for some systems)
    • Session isolation via Chrome user data directory
    • No data sent to third parties

Best Practices

Troubleshooting

Tools Not Showing in Poke

  1. Restart the server
  2. Delete and re-add the MCP connection in Poke
  3. Check server logs for tools/list request
  4. Verify ngrok tunnel is active

Items Not Added to Cart

  1. Verify you’re logged into Amazon:
    • Check the browser window (if visible)
    • Or ask Poke to run check_login
  2. If not logged in:
    • Set HEADLESS=false
    • Restart server
    • Log in manually in the browser window

Connection Keeps Dropping

Computer Sleep Mode

Development

Project Structure

amazon-mcp/
├── src/
│   ├── server.ts       # MCP server + SSE implementation
│   ├── amazon.ts       # Amazon automation logic
│   ├── browser.ts      # Puppeteer browser management
│   └── types.ts        # TypeScript interfaces
├── dist/               # Compiled JavaScript (gitignored)
├── user-data/          # Chrome session data (gitignored)
├── .env                # Environment config (gitignored)
└── package.json

Running in Development

npm run dev    # Uses ts-node, no build required

Building

npm run build  # Compiles TypeScript to dist/

Testing

Health Check

curl http://localhost:3000/health

Expected response:

{"status":"ok","server":"amazon-mcp-server"}

Test SSE Connection

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3000/sse

Should maintain an open connection with heartbeats.

Compliance Notes

This project is designed for personal, single-user use only. It is not intended for:

If you need enterprise-grade compliance, consider:

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Author

Created by @meimakes

Note: Keep your computer awake while running the server. The ngrok tunnel and SSE connections are sensitive to network interruptions.

This site is open source. Improve this page.