Alexa Shopping List MCP

Alexa购物清单

Example Usage in Claude Desktop

关于

无缝管理您的Alexa购物清单。立即添加、删除和查看项目。 使用Claude或Cursor等人工智能助手，通过MCP与您的Alexa购物清单进行交互。

\[！警告\] 需要手动身份验证和Cookie刷新 此工具使用通过手动登录过程提取的浏览器Cookie。 亚马逊会话过期。 你 将 当工具停止工作时，需要定期重新运行登录脚本（步骤5和6）。

组件

1. API服务器(src/api): Docker容器（FastAPI）与Alexa对话。
2. MCP服务器(src/mcp): 提供MCP工具的本地脚本。API服务器的代理。
3. 登录脚本(src/auth): 使用Selenium进行登录和cookie注入的本地脚本。

先决条件

• Python 3.10+
• uv （安装： pip install uv 或查看 星光sh/uv)
• Docker和Docker Compose（或Docker桌面）
• 谷歌Chrome浏览器（用于登录脚本）
• 亚马逊账户（使用Alexa）

设置和运行

1.克隆存储库

# git clone 
cd alexa-mcp

2.配置组件

调整中的设置 config.py 每个组件目录中的文件：

• src/api/config.py：API服务器设置（端口、内部路径）。
• src/auth/config.py：登录脚本设置（Amazon URL、API位置、， 电子邮件/密码).
• src/mcp/config.py：MCP服务器设置（API位置）。

*确保 AMAZON_URL 匹配您的地区和 设置您的 AMAZON_EMAIL 和 AMAZON_PASSWORD 在……里面 src/auth/config.py.* 您只需要临时设置这些，登录脚本就知道要打开哪个亚马逊URL；脚本不再自动使用它们。

3.启动API服务器容器

构建图像并在后台运行API服务器。

docker compose up --build -d alexa_api

*（使用 docker compose logs -f alexa_api 查看日志； docker compose down 停止。)*

4.设置本地环境并安装身份验证依赖项

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

5.运行登录脚本

这将打开一个指向亚马逊登录页面的浏览器窗口。

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

6.手动登录和确认

使用脚本打开的浏览器窗口手动登录。处理亚马逊提供的任何2FA或CAPTCHA步骤。

在浏览器窗口中成功登录亚马逊后，返回运行脚本的终端并按 ENTER.

然后，脚本将尝试提取会话Cookie并将其发送到API服务器。

7.测试API

验证API服务器是否收到Cookie，并可以通过在浏览器中打开此URL（或使用 curl):

http://127.0.0.1:8000/items/all

您应该看到一个JSON响应，其中包含您当前的Alexa购物清单项目。如果您收到错误（如401未授权或503服务不可用），请查看API日志(docker compose logs alexa_api)并可能重新运行步骤5和6。

• API文件： FastAPI自动生成交互式文档。您可以浏览所有可用的端点，并直接在浏览器中进行测试，网址为 http://127.0.0.1:8000/docs.

故障排除

• MCP服务器问题：

- spawn ENOENT （Claude Desktop）：验证中的绝对路径 mcp.json. - 连接错误/断开连接：检查API容器日志(docker compose logs alexa_api).确保API容器正在运行且可访问（检查 src/mcp/config.py). - 导入错误：确保依赖项安装在正确的venv中(uv pip install -r src/mcp/requirements.txt).

• API容器问题：

- 启动失败：检查日志(docker compose logs alexa_api). - 配置错误：验证中的设置 src/api/config.py. - 端口冲突：确保主机端口 8000 （或映射端口）是空闲的。

• 登录脚本问题(src/auth/login.py):

- 导入错误：确保已安装依赖项(uv pip install -r src/auth/requirements.txt). - ModuleNotFoundError: No module named 'distutils' （在Python 3.12+上）：确保 setuptools 被包含在 src/auth/requirements.txt 并且重新安装依赖关系。 - WebDriver错误：确保Chrome已安装/更新。检查 nodriver 兼容性。 - Cookie错误：如果登录失败或成功登录后无法提取Cookie，则会发生Cookie错误。 - API连接错误：确保API容器正在运行且可访问（请检查 src/auth/config.py).检查 docker compose logs alexa_api. - 登录失败：验证中的凭据 src/auth/config.py。检查日志或屏幕截图中提到的意外页面更改或验证码/2FA提示。亚马逊可能会更改选择器(#ap_email, #signInSubmit等等）。

• 工具错误（401未经授权）： 登录失败或Cookie已过期。重新运行登录脚本(python -m src.auth.login).确保凭据在 src/auth/config.py 正确并检查 auth 记录上次运行期间的任何2FA/Captcha问题。

连接MCP客户端（克劳德桌面/光标）

要将此服务器与Claude Desktop或Cursor等MCP客户端一起使用，您需要将其配置添加到客户端的 mcp.json 文件。此文件告诉客户端如何查找和运行本地MCP服务器。

1. 找到MCP客户端的配置文件（通常命名为 mcp.json).位置因客户而异。
2. 打开文件并在主目录中添加以下条目 "mcpServers": { ... } 对象：

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

重要：

• 你 必须 替换占位符绝对路径 /path/to/your/alexa-mcp 在 command, workingDirectory，以及 env.PYTHONPATH 具有实际绝对路径的字段 你的 您计算机上的项目目录。
• 确保 .venv 该位置存在虚拟环境，并且安装了MCP依赖项(uv pip install -r src/mcp/requirements.txt).

1. 保存 mcp.json 文件。
2. 重新启动MCP客户端。“Alexa购物清单MCP”服务器现在应该可用了。

赞助

喜欢这个工具吗？考虑赞助开发者：