alexa-mcp

alexa-mcp

此项目由 AI（Claude Code）开发并维护。请自行斟酌使用。

适用于 Amazon Alexa 的 MCP 服务：列出并控制 Echo 扬声器、Echo Shows 和 Fire TVs，让 Alexa 朗读或播报、运行例程，读取和控制 Alexa 已识别的智能家居设备（恒温器、灯、插座、门锁、车库门、机器人吸尘器、场景），读取和编辑购物清单／待办清单，以及设置或取消闹钟、计时器和提醒。

它通过 alexa-remote2 与 Amazon 的私有 Alexa Web API 通信，也就是 Alexa 应用使用的 API。上述功能都没有公开 API，因此 Amazon 更改相关内容时，服务偶尔可能会出问题。

登录一次

你会在自己的浏览器中登录 Amazon；此服务不会获取你的密码。

• **在聊天中：**让 Claude 登录 Alexa。它会调用 alexa_begin_login 并提供一个 amazon.com 链接。在该链接中登录（输入密码、两步验证码，或按 Amazon 的要求操作），然后你会进入一个空白的 www.amazon.com/ap/maplanding 页面。将该页面的网址粘贴回来，Claude 会调用 alexa_finish_login。
• **托管连接器：**登录页面会显示一个 Sign in to Amazon 按钮，以及一个用于填写同一网址的输入框。
• 终端：npx @chrischall/alexa-mcp login 会打印链接并读取你粘贴的网址（--print 还会将注册信息以一行 base64 的形式写入 ALEXA_REGISTRATION；请将其视为凭据）。

在底层，这使用了 Alexa iOS 应用通过 PKCE 进行的 OAuth 登录。链接中只包含一个质询，相应的密钥会留在服务端；粘贴的网址中的代码只能使用一次，并会在几分钟后过期。完成登录后，系统会在你的账户中注册一个名为 alexa-mcp 的虚拟设备，并将注册信息（刷新令牌和会话 Cookie）保存到 ~/.alexa-mcp/registration.json（权限模式为 0600）。之后无需使用浏览器：每隔几天会根据刷新令牌重新生成 Cookie。若要撤销访问权限，请从你的 Amazon 账户中移除 alexa-mcp 设备（Manage Your Content and Devices → Devices）。登录完成期间，令牌副本会写入 registration-seed.json，并在 registration.json 保存后删除。此修复之前的版本从未删除该文件，因此若要清理较旧的安装，也请删除 ~/.alexa-mcp/registration-seed.json。

工具

工具	功能
alexa_list_devices	Echo 扬声器、Echo Shows、Fire TV 和其他 Alexa 设备及其在线状态（不包括恒温器、灯或插座：这些属于智能家居设备）
alexa_get_now_playing	单台设备的媒体状态
alexa_list_volumes	音量和静音状态（仅限 Amazon 会报告的设备，通常只有少数几台）
alexa_get_do_not_disturb	哪些设备已开启「请勿打扰」
alexa_get_equalizer	扬声器或 Soundbar 的低音／中音／高音
alexa_list_bluetooth	与各 Echo 配对的蓝牙设备，以及正在播放的内容
alexa_list_routines	工作流及其触发条件
alexa_list_smart_home	恒温器、灯、插座、门锁、传感器、群组和场景，以及此服务可向各设备发送的操作
alexa_get_smart_home_state	实时状态：恒温器温度、模式和设定点、湿度、灯的开关／亮度／颜色、门锁状态、传感器、可连接状态
alexa_list_lists / alexa_get_list_items	购物清单和待办清单
alexa_list_alarms_reminders	闹钟、计时器和提醒（附有用于取消的 ID）
alexa_set_volume ✋	设置设备音量
alexa_playback ✋	播放／暂停／下一首／上一首
alexa_stop ✋	停止一台或所有设备：音乐、响铃的闹钟、语音
alexa_speak ✋	在一台设备上播报，或在多台设备上发送公告
alexa_run_builtin ✋	播报天气、交通、新闻简报、笑话、故事、日历等内置内容
alexa_fire_tv ✋	Fire TV 开／关／暂停／继续／返回主页
alexa_set_do_not_disturb ✋	开启或关闭「请勿打扰」
alexa_set_equalizer ✋	设置低音／中音／高音
alexa_run_routine ✋	立即运行一个工作流
alexa_control_smart_home ✋	turnOn / turnOff / setBrightness / setColor / setColorTemperature / sceneActivate
alexa_list_device_modes	设备的模式设置（恒温器风扇模式、吸尘器模式、灯光效果）、当前值和可选项
alexa_set_device_mode ✋	更改其中一种模式，例如将风扇模式设为 Circulate（不包括车库门）
alexa_lock ✋	锁定或解锁智能门锁。解锁会降低安全性；Amazon 可能要求输入语音 PIN 或使用 Alexa 应用
alexa_garage_door ✋	打开或关闭车库门。打开会降低安全性
alexa_set_thermostat ✋	设置恒温器设定点和／或模式，并检查是否在恒温器允许的范围内
alexa_set_vacation_mode ✋	恒温器度假／外出模式（模拟实现）：保存每台恒温器的设置，设为节能设定点，并在关闭时还原
alexa_create_reminder ✋ / alexa_create_timer ✋ / alexa_cancel_alarm_reminder ✋	设置提醒、闹钟或计时器；取消其中一项
alexa_add_list_item ✋ / alexa_update_list_item ✋ / alexa_remove_list_item ✋	编辑清单：添加、勾选／取消勾选、删除
alexa_begin_login / alexa_finish_login	浏览器登录（见上文）
alexa_session_status	配置状态，不访问网络
alexa_healthcheck	Amazon 是否仍接受该会话？

✋ = 需要确认。 支持提示词的客户端会先询问你；在其他环境（claude.ai、Claude Desktop）中，首次调用不会发送任何内容，而是返回预览和 confirmToken，只有再次调用并提供该令牌才会执行操作。

有意不提供：

• 自由文本语音命令（“Alexa，……”、该库的 textCommand）。这类命令可能会购买商品并解锁门锁，却不经过专门的、需确认的工具，因此没有任何工具会发送此类命令。

可以解锁门锁和打开车库门，但只能通过 alexa_lock 和 alexa_garage_door 执行；这两个工具均标记为破坏性操作，且始终需要确认。 度假模式是一种模拟。 Alexa 应用自身的恒温器度假模式无法通过此服务使用的 API 访问（恒温器模式只有 HEAT / COOL / AUTO / OFF），因此不会切换应用中的开关。相反，alexa_set_vacation_mode 会在更改任何设置前，将每个恒温器的模式和设定温度保存到 ~/.alexa-mcp/vacation.json（权限为 0600），然后将制热温度设为 55°、制冷温度设为 85°（或设为你指定的温度）。处于 OFF 状态的恒温器会保持关闭。关闭度假模式时会恢复已保存的设置。重复开启会被拒绝，因此原始设置绝不会被覆盖。

配置

变量	默认值	用途
ALEXA_REGISTRATION	—	注册 JSON，或 login --print 输出的 base64 行。状态文件存在时可选。如果格式错误但状态文件有效，则使用状态文件并记录警告。
ALEXA_STATE_DIR	~/.alexa-mcp	registration.json 和待处理登录信息的存放位置。
ALEXA_AMAZON_PAGE	amazon.com	账户使用的 Amazon 站点（或注册信息中记录的站点）。
ALEXA_ACCEPT_LANGUAGE	en-US	发送给 Amazon 的 Accept-Language。
MCP_CONFIRM_MODE	ask-user	ask-user / auto / refuse — 模型使用 confirmToken 前是否必须先在聊天中获得你的批准。
MCP_CONFIRM_ELICITATION	on	设为 off 后，即使客户端声明支持，也会跳过确认提示。

如果 ALEXA_REGISTRATION 和状态文件同时存在，则以 tokenDate 较新的那份为准，无论它属于哪个设备（时间相同则使用状态文件中的副本，因为它是刷新后的副本）。因此，即使仍设置着较旧的 ALEXA_REGISTRATION，通过 alexa_finish_login 重新登录也能在重启后生效；而新粘贴的 ALEXA_REGISTRATION 会优先于旧状态文件。

从 0.1 升级

0.2.0 更改了连接器的登录方式。粘贴 ALEXA_REGISTRATION 字段的方式已替换为浏览器登录流程（mint.yaml 中的 auth.flow：点击 Sign in to Amazon 链接，然后粘贴你最终到达的地址）。现有托管注册信息必须切换到新流程：通过该流程重新登录一次。不再需要 alexa-mcp login --port <n>：该标志会被忽略并显示提示，因为现在会在你自己的浏览器中完成登录。

托管

mint.yaml 描述了 mcp-host 的服务配置：每位用户对应一个子进程（identity.perUserChild）、两步式 auth.flow（开始 → 在 amazon.com 登录 → 粘贴地址），注册信息会保存在每位用户自己的数据目录中。

开发

npm install
npm test          # typecheck + vitest (no network)
npm run build     # tsc + esbuild bundle (dist/bundle.js is the .mcpb entry)

经过验证的响应格式和主机信息，请参阅 docs/ALEXA-API.md。