Alexa Shopping List MCP server

Alexa Shopping List is a tool that allows you to manage your Alexa shopping list through the Model Context Protocol (MCP). This integration enables AI assistants like Claude or Cursor to add, remove, and view your Alexa shopping list items seamlessly.

Prerequisites

• Python 3.10+
• uv (Install: pip install uv or visit astral.sh/uv)
• Docker & Docker Compose (or Docker Desktop)
• Google Chrome (for login script)
• Amazon Account (with Alexa)

Installation

1. Clone Repository

# git clone <repository_url>
cd alexa-mcp

2. Configure Components

Adjust settings in the following configuration files:

• src/api/config.py: API server settings (port, internal paths)
• src/auth/config.py: Login script settings (Amazon URL, API location, credentials)
• src/mcp/config.py: MCP server settings (API location)

Ensure AMAZON_URL matches your region and set your AMAZON_EMAIL and AMAZON_PASSWORD in src/auth/config.py.

3. Start API Server Container

docker compose up --build -d alexa_api

To view logs: docker compose logs -f alexa_api
To stop: docker compose down

4. Set Up Local Environment

# In the project root
uv venv
source .venv/bin/activate
uv pip install -r src/auth/requirements.txt

5. Run Login Script

# Ensure virtual env is active
python -m src.auth.login

6. Complete Authentication

1. When the script opens a browser window, manually log in to your Amazon account
2. Handle any 2FA or CAPTCHA challenges
3. After successful login, return to the terminal and press ENTER
4. The script will extract your session cookies and send them to the API server

7. Verify Setup

Test that the API server can access your list by opening: http://127.0.0.1:8000/items/all

You should see a JSON response with your Alexa shopping list items.

API documentation is available at: http://127.0.0.1:8000/docs

Connecting with MCP Clients

To use this server with Claude Desktop, Cursor, or other MCP clients:

1. Locate your MCP client's mcp.json configuration file
2. Add the following entry to the "mcpServers": { ... } object:

"alexa-shopping-list": {
    "displayName": "Alexa Shopping List MCP",
    "description": "MCP Server for interacting with Alexa shopping list via local API",
    "command": "/path/to/your/alexa-mcp/.venv/bin/python",
    "args": [
      "-m",
      "src.mcp.mcp_server"
    ],
    "workingDirectory": "/path/to/your/alexa-mcp",
    "env": {
      "PYTHONPATH": "/path/to/your/alexa-mcp"
    }
}

Important: Replace all instances of /path/to/your/alexa-mcp with the actual absolute path to your project directory. Also ensure you've installed the MCP dependencies with uv pip install -r src/mcp/requirements.txt.

3. Save the file and restart your MCP client

Troubleshooting

MCP Server Issues

• spawn ENOENT (Claude Desktop): Verify absolute paths in mcp.json
• Connection errors: Check API container logs and ensure it's running
• Import errors: Verify dependencies in the correct virtual environment

API Container Issues

• Check logs with docker compose logs alexa_api
• Verify settings in src/api/config.py
• Ensure port 8000 is available

Authentication Issues

• If you get 401 Unauthorized errors, your session likely expired
• Rerun the login script with python -m src.auth.login
• Verify your credentials in src/auth/config.py

Login Script Problems

• For WebDriver errors, check Chrome installation
• For ModuleNotFoundError: No module named 'distutils' on Python 3.12+, install setuptools
• Amazon may occasionally change their login page structure

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.