Alexa 购物清单

关于

无缝管理您的 Alexa 购物清单。即时添加、删除和查看项目。 通过 MCP 使用像 Claude 或 Cursor 这样的 AI 助手与您的 Alexa 购物清单进行交互。

[!警告] 需要手动认证及刷新 Cookie

此工具使用通过手动登录过程提取的浏览器 Cookie。 Amazon 会话过期。 当工具停止工作时，您必须定期重新运行登录脚本（步骤 5 和 6）。

组件

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

预备条件

• Python 3.10+
• uv（安装：pip install uv 或参见 astral.sh/uv）
• Docker 及 Docker Compose（或 Docker Desktop）
• Google Chrome（用于登录脚本）
• Amazon 账户（带有 Alexa）

设置与运行

1. 克隆仓库

# git clone <repository_url>
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 符合您的区域，并在 src/auth/config.py 中设置您的 AMAZON_EMAIL 和 AMAZON_PASSWORD。 您只需临时设置这些信息，以便登录脚本知道要打开哪个 Amazon URL；脚本不再自动使用它们。

3. 启动 API 服务器容器

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

docker compose up --build -d alexa_api

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

4. 设置本地环境并安装认证依赖项

# 在项目根目录（alexa-mcp）
uv venv
source .venv/bin/activate
uv pip install -r src/auth/requirements.txt

5. 运行登录脚本

这将在浏览器中打开 Amazon 登录页面。

# 确保虚拟环境已激活
python -m src.auth.login

6. 手动登录及确认

使用脚本打开的浏览器窗口手动登录。处理 Amazon 提出的任何 2FA 或验证码步骤。

成功登录到该浏览器窗口中的 Amazon 后，返回运行脚本的终端并按 ENTER。

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

7. 测试 API

验证 API 服务器是否收到 Cookie 并能访问您的列表，通过在浏览器中打开以下 URL（或使用 curl）：

http://127.0.0.1:8000/items/all

您应该看到包含当前 Alexa 购物清单项目的 JSON 响应。如果您遇到错误（如 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）。
  • 导入错误：确保在正确的虚拟环境中安装了依赖项（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，则会发生此错误。
  • API 连接错误：确保 API 容器正在运行且可访问（检查 src/auth/config.py）。检查 docker compose logs alexa_api。
  • 登录失败：验证 src/auth/config.py 中的凭据。检查日志或截图中提到的意外页面更改或验证码/2FA 提示。Amazon 可能更改了选择器（如 #ap_email、#signInSubmit 等）。
• 工具错误（401 未授权）：登录失败或 Cookie 过期。重新运行登录脚本（python -m src.auth.login）。确保 src/auth/config.py 中的凭据正确，并检查 auth 日志以了解上次运行期间的任何 2FA/验证码问题。

连接 MCP 客户端（Claude Desktop / Cursor）

要使用像 Claude Desktop 或 Cursor 这样的 MCP 客户端，您需要在其 mcp.json 文件中添加其配置。此文件告诉客户端如何找到并运行您的本地 MCP 服务器。

1. 找到您的 MCP 客户端配置文件（通常名为 mcp.json）。位置取决于客户端。
2. 打开文件并在主 "mcpServers": { ... } 对象内添加以下条目：

    "alexa-shopping-list": {
        "displayName": "Alexa 购物清单 MCP",
        "description": "通过本地 API 与 Alexa 购物清单交互的 MCP 服务器",
        "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 替换为您机器上项目的实际绝对路径。
• 确保 .venv 虚拟环境存在于该位置并且已安装 MCP 依赖项（uv pip install -r src/mcp/requirements.txt）。

3. 保存 mcp.json 文件。
4. 重启您的 MCP 客户端。“Alexa 购物清单 MCP”服务器现在应该可用。

赞助

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