内容
# alexa-mcp
> 一个遵循MCP（模型上下文协议）的服务器，允许Claude以及其他兼容MCP的大型语言模型控制亚马逊Alexa设备：发布公告、发送文本命令、管理智能家居群组、运行例行程序等。
[](./LICENSE)
[](https://nodejs.org)
基于[`alexa-remote2`](https://github.com/Apollon77/alexa-remote)（亚马逊内部Alexa API的活跃维护客户端）构建。
---
## 功能特点
通过MCP暴露的18种工具，按领域分组：
**设备**
- `alexa_list_devices` — 列出账户中的每个Echo设备，包含序列号、类型和在线状态
- `alexa_set_volume` / `alexa_get_volumes` — 读取或更改每个设备的音量
- `alexa_do_not_disturb` — 在设备上切换请勿打扰模式
**语音与消息**
- `alexa_announce` — 向特定的Echo设备推送语音公告
- `alexa_text_command` — 发送文本命令，模拟语音输入（例如“打开厨房灯”）
- `alexa_speak_ssml` — 使Alexa使用SSML进行细粒度语音控制
**智能家居**
- `alexa_list_smarthome_devices` — 列出所有已配对的智能家居设备（灯、传感器、开关等）
- `alexa_query_device` — 读取一个或多个设备的当前状态
- `alexa_list_groups` / `alexa_create_group` / `alexa_update_group` / `alexa_delete_group` — 管理房间/群组
**例行程序**
- `alexa_list_routines` — 列出账户中的每个例行程序
- `alexa_execute_routine` — 通过传递自动化定义来运行例行程序
**列表**
- `alexa_list_lists` — 列出购物/待办/自定义列表
- `alexa_get_list_items` — 从列表中读取项目
- `alexa_add_list_item` — 在列表中追加项目
---
## 要求
- **Node.js ≥ 18**
- 具有至少一个已注册的Alexa/Echo设备的亚马逊账户
- 兼容MCP的客户端（[Claude Desktop](https://claude.ai/download)，Claude Code等）
---
## 安装
```bash
git clone https://github.com/<your-user>/alexa-mcp.git
cd alexa-mcp
npm install
```
---
## 身份验证
亚马逊的Alexa API是私有的，需要基于浏览器的真实登录（无API密钥）。MCP附带了一个交互式身份验证助手：
```bash
npm run auth
```
这将：
1. 在`http://localhost:3457`启动本地HTTP代理。
2. 打印一个URL，您需要在浏览器中打开它。
3. 您使用正常的亚马逊凭证登录（正确处理2FA/OTP，因为它是实际的亚马逊页面，只是代理）。
4. 代理拦截生成的会话cookie并将它们保存到`.auth-data/auth.json`（模式`0600`，从不提交 — 参见[安全](#安全)）。
您只需要运行一次此操作。从那时起，`alexa-remote2`会自动刷新令牌。如果您看到`身份验证失败`，只需重新运行`npm run auth`。
> **区域说明：** 助手默认为`amazon.com`和西班牙语区域设置（`es-MX`）。如果您的账户位于其他市场（`amazon.de`、`amazon.co.uk`、`amazon.com.mx`等），请相应地编辑`src/auth.js`。欢迎PR使此配置可通过环境变量进行。
### 多个Alexa账户（多实例）
单个此存储库的克隆可以通过将`ALEXA_MCP_AUTH_DIR`环境变量设置为指向每个实例的目录来为**多个Alexa账户**提供服务：
```bash
# 身份验证个人账户
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/personal npm run auth
# 身份验证第二个（例如工作）账户
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/work npm run auth
```
每个实例在其自己的目录中保留自己的`auth.json`，因此它们永远不会发生冲突。默认情况下（当`ALEXA_MCP_AUTH_DIR`未设置时），对于简单的单账户情况，保留项目本地的`.auth-data/`。参见下面的[与Claude Desktop一起使用](#与Claude-Desktop一起使用)，了解如何从同一代码注册两个MCP服务器。
---
## 与Claude Desktop一起使用
将服务器添加到您的Claude Desktop配置中：
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"alexa": {
"command": "node",
"args": ["/absolute/path/to/alexa-mcp/src/index.js"]
}
}
}
```
重新启动Claude Desktop。Alexa工具应该出现在工具选择器中。
## 与Claude Code一起使用
```bash
claude mcp add alexa -- node /absolute/path/to/alexa-mcp/src/index.js
```
## 与其他MCP客户端一起使用
任何通过stdio支持MCP的客户端都有效。将它指向`node /absolute/path/to/alexa-mcp/src/index.js`。
---
## 示例
配置完成后，您可以问Claude：
- *"列出我的Echo设备并告诉我哪些设备在线"*
- *"告诉厨房的Echo设备提醒大家晚餐准备好了"*
- *"将客厅扬声器的音量降低到30%"*
- *"运行‘晚安’例行程序"*
- *"将牛奶和鸡蛋添加到我的购物清单中"*
- *"办公室里有哪些灯目前是开着的？"*
---
## 安全
- **`.auth-data/`被git忽略**，其中包含您的会话cookie。请像对待密码一样保护它 — 任何拥有该文件的人都可以控制您的Alexa账户。
- 身份验证文件以模式`0600`（仅所有者可读）写入。
- 此服务器**本地运行**，直接与亚马逊通信。无需第三方服务。
- MCP传输**仅限stdio**。服务器从不打开网络端口；它仅通过标准输入/输出与其父进程（Claude Desktop / Claude Code）通信。
- `@modelcontextprotocol/sdk`的与HTTP相关的传递依赖项（`hono`、`express`等）存在于`node_modules`中，但**从未被此服务器执行**。
### 已知上游咨询
`alexa-cookie2`（`alexa-remote2`的传递依赖项）当前固定了旧版本的`cookie`（`<0.7.0`），被标记为**低**严重性。修复程序不可用，除非将`alexa-remote2`降低7个主要版本，这将破坏集成。该漏洞仅影响恶意构造的cookie名称的解析，不影响正常使用。请跟踪上游：[Apollon77/alexa-cookie2](https://github.com/Apollon77/alexa-cookie2)。
---
## 故障排除
| 症状 | 尝试方法 |
|---|---|
| `身份验证失败` / 命令静默失败 | 重新运行`npm run auth` |
| 命令“成功”但设备无反应 | 在官方Alexa应用程序中验证设备是否在线 |
| MCP在Claude中不显示 | 确认客户端配置中的路径是绝对的，然后重启客户端 |
| 错误的语言/地区 | 编辑`src/auth.js`中的`amazonPage`和`acceptLanguage`，然后重新身份验证 |
| 身份验证期间端口3457上的`EADDRINUSE` | 终止正在使用端口3457的任何进程，或更改`src/auth.js`中的`PROXY_PORT` |
---
## 项目结构
```
alexa-mcp/
├── src/
│ ├── index.js # MCP服务器入口点 — 注册所有18种工具
│ ├── alexa-client.js # alexa-remote2的薄包装
│ └── auth.js # 交互式身份验证流程（运行一次）
├── .auth-data/ # OAuth令牌（在首次身份验证时创建，git忽略）
├── package.json
├── LICENSE
└── README.md
```
---
## 贡献
欢迎提出问题和PR。一些值得解决的想法：
- 使区域/语言环境可通过环境变量配置，而不是编辑`src/auth.js`
- 暴露更多`alexa-remote2`功能（定时器、闹钟、音乐提供商）
- 添加自动化测试套件（目前没有 — 验证是手动的）
- 用于更轻松部署的Docker镜像
---
## 致谢
- [Apollon77](https://github.com/Apollon77) 维护[`alexa-remote2`](https://github.com/Apollon77/alexa-remote)，它完成了与亚马逊通信的实际繁重工作。
- Anthropic的[模型上下文协议](https://modelcontextprotocol.io)团队。
---
## 许可证
[MIT](./LICENSE) © Renato Ascencio
