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/<your-user>/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.

Region note: the helper defaults to amazon.com and Spanish locale (es-MX). If your account lives in another marketplace (amazon.de, amazon.co.uk, amazon.com.mx, etc.) edit src/auth.js accordingly. PRs welcome to make this configurable via env vars.

Multiple Alexa accounts (multi-instance)

A single clone of this repo can serve multiple Alexa accounts by setting the ALEXA_MCP_AUTH_DIR env var to point at a per-instance directory:

# Authenticate the personal account
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/personal npm run auth

# Authenticate a second (e.g. work) account
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/work npm run auth

Each instance keeps its own auth.json in its own directory, so they never collide. The default (when ALEXA_MCP_AUTH_DIR is unset) remains the project-local .auth-data/ for the simple single-account case. See Usage with Claude Desktop below for how to register two MCP servers from the same code.

---

Usage with Claude Desktop

Add the server to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "alexa": {
      "command": "node",
      "args": ["/absolute/path/to/alexa-mcp/src/index.js"]
    }
  }
}

Restart Claude Desktop. The Alexa tools should appear in the tool picker.

Usage with Claude Code

claude mcp add alexa -- node /absolute/path/to/alexa-mcp/src/index.js

Usage with other MCP clients

Any client that speaks MCP over stdio works. Point it at node /absolute/path/to/alexa-mcp/src/index.js.

---

Examples

Once configured, you can ask Claude things like:

• "List my Echo devices and tell me which ones are online"
• "Tell the kitchen Echo to remind everyone dinner is ready"
• "Lower the volume of the living room speaker to 30%"
• "Run the 'Good night' routine"
• "Add milk and eggs to my shopping list"
• "Which lights are currently on in the office?"

---

Security

• .auth-data/ is git-ignored and contains your session cookies. Treat it like a password — anyone with that file can control your Alexa account.
• The auth file is written with mode 0600 (owner-read-only).
• This server runs locally and talks to Amazon directly. No third-party services are involved.
• The MCP transport is stdio only. The server never opens a network port; it only talks to its parent process (Claude Desktop / Claude Code) via standard input/output.
• The HTTP-related transitive dependencies of @modelcontextprotocol/sdk (hono, express, etc.) are present in node_modules but are never executed by this server.

Known upstream advisory

alexa-cookie2 (a transitive dep of alexa-remote2) currently pins an old version of cookie (<0.7.0) flagged as low severity. The fix is not available without downgrading alexa-remote2 by 7 majors, which would break the integration. The vulnerability only affects parsing of malformed cookie names and does not impact normal use. Track upstream: Apollon77/alexa-cookie2.

---

Troubleshooting

Symptom	What to try
Authentication failed / commands silently fail	Re-run npm run auth
Commands "succeed" but the device does nothing	Verify the device is online in the official Alexa app
MCP doesn't appear in Claude	Confirm the path in your client config is absolute, then restart the client
Wrong language / region	Edit amazonPage and acceptLanguage in src/auth.js, then re-auth
EADDRINUSE on port 3457 during auth	Kill whatever is using port 3457, or change PROXY_PORT in src/auth.js

---

Project structure

alexa-mcp/
├── src/
│   ├── index.js         # MCP server entry point — registers all 18 tools
│   ├── alexa-client.js  # Thin wrapper around alexa-remote2
│   └── auth.js          # Interactive auth flow (run once)
├── .auth-data/          # OAuth tokens (created at first auth, git-ignored)
├── package.json
├── LICENSE
└── README.md

---

Contributing

Issues and PRs welcome. Some ideas worth tackling:

• Make region / locale configurable via env vars instead of editing src/auth.js
• Expose more alexa-remote2 capabilities (timers, alarms, music providers)
• Add an automated test suite (currently none — verification is manual)
• Docker image for easier deployment

---

Acknowledgments

• Apollon77 for maintaining alexa-remote2, which does the actual heavy lifting of talking to Amazon.
• The Model Context Protocol team at Anthropic.

---

License

MIT © Renato Ascencio