alexa-mcp

An MCP (Model Context Protocol) server that lets Claude — and any other MCP-compatible LLM — control Amazon Alexa devices: speak announcements, send text commands, manage smart-home groups, run routines, and more.

Built on top of alexa-remote2 (the actively maintained client for Amazon’s internal Alexa API).

---

Features

18 tools exposed over MCP, grouped by domain:

Devices

• alexa_list_devices — list every Echo in the account with serial, type, online status
• alexa_set_volume / alexa_get_volumes — read or change volume per device
• alexa_do_not_disturb — toggle DND on a device

Voice & messaging

• alexa_announce — push a spoken announcement to a specific Echo
• alexa_text_command — send a text command as if you spoke it (“turn on the kitchen lights”)
• alexa_speak_ssml — make Alexa speak SSML for fine-grained voice control

Smart home

• alexa_list_smarthome_devices — list all paired smart-home devices (lights, sensors, switches…)
• alexa_query_device — read the current state of one or more devices
• alexa_list_groups / alexa_create_group / alexa_update_group / alexa_delete_group — manage rooms / groups

Routines

• alexa_list_routines — list every routine in the account
• alexa_execute_routine — run a routine by passing its automation definition

Lists

• alexa_list_lists — list shopping / to-do / custom lists
• alexa_get_list_items — read items from a list
• alexa_add_list_item — append an item to a list

---

Requirements

• Node.js ≥ 18
• An Amazon account with at least one registered Alexa/Echo device
• An MCP-compatible client (Claude Desktop, Claude Code, etc.)

---

Installation

git clone https://github.com//alexa-mcp.git
cd alexa-mcp
npm install

---

Authentication

Amazon’s Alexa API is private and requires a real browser-based login (no API keys). The MCP ships with an interactive auth helper:

npm run auth

This will:

1. Start a local HTTP proxy on http://localhost:3457.
2. Print a URL you open in your browser.
3. You log in with your normal Amazon credentials (handles 2FA / OTP correctly because it’s the actual Amazon page, just proxied).
4. The proxy intercepts the resulting session cookies and saves them to .auth-data/auth.json (mode 0600, never committed — see Security).

You only need to run this once. From then on, alexa-remote2 refreshes tokens automatically. If you ever see Authentication failed, just re-run npm run auth.