Alexa Shopping List

🚀 Alexa Shopping List Manager

Seamlessly manage your Alexa shopping list. Add, delete, and view items instantly.

🚀 Quick Start

This tool enables seamless management of your Alexa shopping list. You can add, delete, and view items right away. Interact with AI assistants like Claude or Cursor through MCP, and use this tool to communicate locally with your Alexa shopping list.

⚠️ Important Note

Manual authentication and cookie refresh are required. This tool uses browser cookies extracted through a manual login process. Amazon sessions expire. You must periodically re-run the login script (Steps 5 and 6) when the tool stops working.

✨ Features

Components

1. API Server (src/api): A Docker container using FastAPI to communicate with Alexa.
2. MCP Server (src/mcp): A local script providing the MCP tool. It acts as a proxy to the API server.
3. Login Script (src/auth): A local script for manual login and cookie injection using Selenium.

📦 Installation

Prerequisites

• Python 3.10+
• uv (Installation: pip install uv or see astral.sh/uv)
• Docker and Docker Compose (or Docker Desktop)
• Google Chrome (for the login script)
• An Amazon account with Alexa

Setup and Run

1. Clone the repository

# git clone <repository_url>
cd alexa-mcp

2. Configure settings Edit src/auth/config.py to reflect your Amazon credentials:

AMAZON_EMAIL = "your_amazon_email"
AMAZON_PASSWORD = "your_amazon_password"

3. Install dependencies Run the following commands in the project's root directory:

pip install -r src/api/requirements.txt
pip install -r src/auth/requirements.txt
pip install -r src/mcp/requirements.txt

4. Start the API server Run the following command from the project root directory:

uvicorn src.api.main:app --reload

By default, the API will be available at http://localhost:8000. 5. Start the MCP server Run the following command from the project root directory:

uvicorn src.mcp.mcp_server:app --reload

💻 Usage Examples

Connecting MCP Clients (Claude Desktop / Cursor)

To use this server with MCP clients like Claude Desktop or Cursor, you need to add its configuration to the mcp.json file of the client. This file tells the client how to find and run your local MCP server.

1. Locate your MCP client configuration file (usually named mcp.json). The location varies depending on the client.
2. Open the file and add the following entry inside the main "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 Notes:

• You must replace the placeholder absolute path /path/to/your/alexa-mcp with the actual absolute path of the project on your computer.
• Ensure that the .venv virtual environment exists at that location and that the MCP dependencies are installed (run uv pip install -r src/mcp/requirements.txt).

3. Save the mcp.json file.
4. Restart your MCP client. You should now be able to find the "Alexa Shopping List MCP" server.

🤝 Support

Like this tool? Consider supporting the developer: