alexa-mcp
Provides control of Amazon Alexa/Echo devices, enabling announcements, text voice commands, smart-home management, routine execution, sensor queries, media playback, alarms, reminders, and device settings.
Allows playing music from Amazon Music on Alexa/Echo devices via search phrase and optional provider selection.
Allows playing music from Apple Music on Alexa/Echo devices via search phrase and optional provider selection.
Allows playing Audible audiobooks on Alexa/Echo devices via search phrase.
Allows playing music from Spotify on Alexa/Echo devices via search phrase and optional provider selection.
Allows playing TuneIn radio content on Alexa/Echo devices via search phrase and optional provider selection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@alexa-mcp announce 'dinner is ready' on the kitchen Echo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
alexa-mcp
A robust, TypeScript-based MCP (Model Context Protocol) server that lets Claude, Perplexity, and any other MCP-compatible LLM control Amazon Alexa devices: speak announcements, execute text voice commands, manage smart-home groups, run routines, query sensor states, and more.
Powered by a native TypeScript Alexa Remote engine (src/alexa-remote/) with complete compile-time type safety, automated tests, and dual-transport architecture (Stdio + Streamable HTTP / SSE).
Architecture & Transports
alexa-mcp offers two flexible transport modes:
┌────────────────────────────────────────────────────────────────────────┐
│ Clients │
│ Claude Desktop │ Claude Code │ Antigravity IDE │ Perplexity │ Web UIs │
└────────────────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ │
[1] Stdio Transport (Local) [2] HTTP / SSE Transport
node dist/index.js (or src/index.js) node dist/server.js
• Standard input/output pipe • Streamable HTTP (POST /mcp)
• Opens no network ports • Legacy SSE (GET /sse)
• Ideal for desktop assistants • CORS-enabled for web/remote
│ │
└────────────────────────┬────────────────────────┘
▼
┌───────────────────────────────┐
│ AlexaClient │
│ • Session token cache │
│ • Atomic 0600/0700 storage │
│ • Amazon Alexa REST & Push │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ Amazon Alexa API │
│ Echoes • Smart Home • Rooms │
└───────────────────────────────┘Stdio Transport (
src/index.ts/dist/index.js/src/index.js): Standard input/output communication for local LLM clients (Claude Desktop, Claude Code, Antigravity IDE). Opens no network ports.Streamable HTTP & SSE Server (
src/server.ts/dist/server.js): High-performance Express server supporting the modern MCP Streamable HTTP specification (POST /mcporPOST /) as well as Legacy SSE (GET /ssewithPOST /messages). Includes CORS headers and session management, ideal for remote LLMs, Perplexity, Open WebUI, and Cloudflare Tunnels.
Related MCP server: alexa-mcp
Features (32 Tools)
Every tool is strictly typed with Zod schema validation and comprehensive error handling:
1. Echo Devices, Audio & Voice
Tool Name | Description | Key Arguments |
| List all Amazon Echo devices with serial numbers, model types, and online status | None |
| Set device volume (0–100) |
|
| Read current volume levels across all Echo devices | None |
| Enable or disable Do Not Disturb mode |
|
| Push a spoken announcement with chime to an Echo |
|
| Send any voice command as text (e.g., "turn on kitchen lights") |
|
| Make Alexa speak plain text directly (no chime) |
|
| Speak SSML markup with pauses, rate, pitch, and emphasis |
|
2. Direct Smart Home & Room Management
Tool Name | Description | Key Arguments |
| List paired smart-home entities (lights, plugs, thermostats, locks) | None |
| Query real-time power, brightness, or sensor states |
|
| Direct smart home control: turn on/off, brightness, temperature, locks |
|
| List configured smart-home groups/rooms and assigned appliances | None |
| Create a new room/group and assign appliance IDs |
|
| Update name and appliances in an existing room/group |
|
| Remove a smart-home group/room |
|
3. Media Streaming & Audio Processing
Tool Name | Description | Key Arguments |
| Stream music via Amazon Music, Spotify, Apple Music, TuneIn, Deezer |
|
| Play audiobooks from Audible on a target Echo |
|
| Control playback: stop, pause, play, next, previous (supports "all") |
|
| Adjust bass, midrange, and treble levels (-6 to +6 dB) |
|
4. Reminders, Alarms & Notifications
Tool Name | Description | Key Arguments |
| Schedule spoken reminders with ISO 8601 timestamps or epoch ms |
|
| List active alarms, timers, and reminders across all devices |
|
| Adjust alarm and timer volume independently from music |
|
5. Routine Behaviors, Sounds & Fire TV
Tool Name | Description | Key Arguments |
| Play built-in sound effects (bells, doorbells, boings, applause, buzzers) |
|
| Speak curated phrases (good morning, compliments, birthday, etc.) |
|
| Trigger native routine behaviors (weather, traffic, flash briefing, jokes) |
|
| Remote control for Fire TV / Cube (power, pause, resume, home) |
|
| List all routines, trigger phrases, and sequence actions | None |
| Trigger an existing automation routine |
|
6. Lists & Voice History
Tool Name | Description | Key Arguments |
| List shopping, to-do, and custom lists | None |
| Retrieve all items from a specified list |
|
| Append a new item to a shopping or to-do list |
|
| Retrieve recent voice interaction history, utterances, and devices |
|
Requirements
Node.js ≥ 18.0.0
An Amazon account with at least one registered Alexa/Echo device
An MCP-compatible client (Claude Desktop, Claude Code, Antigravity IDE, Perplexity, etc.)
Installation & Setup
# Clone repository
git clone https://github.com/james----/alexa-mcp.git
cd alexa-mcp
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run automated tests
npm testAuthentication
Amazon's Alexa API is private and requires a browser-based login. The server includes an interactive authentication helper:
npm run authWhat npm run auth does:
Starts a secure local HTTP proxy on
127.0.0.1:3457(automatically opens your default browser on macOS).You log in to your Amazon account securely. Handles 2FA / OTP seamlessly because it proxies Amazon's real authentication pages.
The proxy captures both the session cookies and the device registration (
macDms) Amazon issues.Credentials are automatically saved to
.auth-data/auth.jsonwith owner-only permissions (0600, directory0700).
You only need to run this once. The client refreshes the token automatically during normal operation.
Why manual cookie pasting is unsupported:
The Alexa client gates initialization on macDms (device private key and ADP token) minted during browser registration. A raw session cookie lacks macDms, causing infinite initialization loops. The browser proxy is the only supported, reliable authentication mechanism.
Multi-Account / Multi-Instance Setup
To serve multiple Alexa accounts from a single installation, point ALEXA_MCP_AUTH_DIR to a dedicated directory per instance:
# Authenticate personal account
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/personal npm run auth
# Authenticate work / second account
ALEXA_MCP_AUTH_DIR=~/.alexa-mcp/work npm run authEach instance maintains its own credentials in isolation.
Client Configurations
1. Claude Desktop (Stdio)
Edit your Claude Desktop configuration:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"alexa": {
"command": "node",
"args": ["/absolute/path/to/alexa-mcp/dist/index.js"]
}
}
}Backward Compatibility: Existing client configurations pointing to
src/index.jscontinue working seamlessly through the built-in forwarder shim.
2. Claude Code (CLI)
claude mcp add alexa -- node "$(pwd)/dist/index.js"Verify connection:
claude mcp list3. Streamable HTTP / SSE Server (Remote Clients & Web UIs)
Run the server:
# Production
npm run serve
# Development (hot reload)
npm run serve:devBy default, the server listens on 0.0.0.0:8000 (configurable via PORT environment variable):
Streamable HTTP Endpoint (Recommended):
http://localhost:8000/mcporhttp://localhost:8000/Legacy SSE Endpoint:
http://localhost:8000/sse(messages atPOST /messages)
Configure in remote MCP clients (e.g., Perplexity, Open WebUI, LibreChat):
{
"mcpServers": {
"alexa": {
"url": "http://localhost:8000/mcp"
}
}
}Running as a Background Service (macOS LaunchAgent)
To run alexa-mcp continuously in the background (auto-starts on login, survives reboots, and auto-recovers on crashes):
# Install and start the LaunchAgent background service
npm run service:install
# Check service status, active PID, network port, and recent logs
npm run service:status
# View live streaming logs
npm run service:logs
# Restart or reload the service
npm run service:restart
# Stop or start the service
npm run service:stop
npm run service:start
# Uninstall the LaunchAgent
npm run service:uninstallShell Shortcuts (~/.zshrc / ~/.bashrc)
You can install convenient shell shortcuts into your ~/.zshrc (or ~/.bashrc) automatically:
# Install shortcuts into your active shell config (~/.zshrc or ~/.bashrc)
npm run service:shortcuts
# Remove shortcuts
npm run service:shortcuts:removeOnce installed and reloaded (source ~/.zshrc), you can use:
astatusoralexa statusalogsoralexa logsarestartoralexa restartastoporalexa stopastartoralexa start
The service runs via macOS launchd (~/Library/LaunchAgents/com.vd0.alexa-mcp.plist) and writes logs to logs/server.launchd.log.
Environment Variables
Variable | Default | Purpose |
|
| Path to store |
|
| Amazon marketplace host (e.g., |
|
| Preferred HTTP Accept-Language header (e.g., |
|
| Proxy language parameter (e.g., |
|
| Local port used exclusively during |
|
| HTTP port used by |
Development & Scripts
Command | Action |
| Compiles TypeScript source to |
| Runs |
| Runs the full automated test suite (builds first) |
| Runs the compiled Stdio server ( |
| Runs the Stdio server directly in TS via |
| Starts the production HTTP/SSE server in foreground ( |
| Starts the HTTP/SSE server in TS via |
| Installs and starts the LaunchAgent background service |
| Shows status, PID, port listener, and recent logs |
| Streams live logs from the background service |
| Restarts the background service |
| Stops the background service |
| Starts the background service |
| Automatically installs shell shortcuts into |
| Removes shell shortcuts from |
| Unloads and removes the background service |
| Starts the interactive browser proxy auth flow |
Testing & Quality Assurance
alexa-mcp ships with a comprehensive test suite built on Node's native test runner (node:test) and @modelcontextprotocol/sdk/inMemory.js:
npm testTest Coverage (24 Tests across 4 Suites):
test/tools.test.ts:In-memory MCP client/server integration.
Verifies registration, schemas, and descriptions for all 32 tools.
Tests mock execution of every smart home, media, audio, reminder, routine, Fire TV, and history tool.
Verifies Zod input validation (e.g. volume out-of-bounds rejection).
Tests error handling when the upstream Alexa API fails.
test/stdio-transport.test.ts:Spawns subprocesses over actual stdin/stdout pipes.
Tests MCP
initializeandtools/listhandshakes onsrc/index.js(backward-compat shim).Tests MCP handshakes on
dist/index.js(compiled binary).Verifies JSON-RPC error codes on unrecognized methods (
-32601).
test/server-transport.test.ts:Express server lifecycle and ephemeral port binding.
Tests CORS headers (
Access-Control-Allow-Origin: *,mcp-session-id).Tests Streamable HTTP
POST /mcpstateful sessions.Tests SSE
GET /ssestreams.Tests automatic
Acceptheader normalization (application/json, text/event-stream).
test/auth-storage.test.ts:Atomic file write verification (temp file -> sync -> atomic rename).
File permission verification (
0600forauth.json,0700for directory).Automatic tightening of insecure directory permissions.
Rejection of corrupt or missing device registrations (
macDms).
See docs/TESTING.md for deep-dive testing documentation.
Security Model
Atomic File Writing: Credentials in
.auth-data/auth.jsonare written to a unique temporary file opened withO_CREAT | O_EXCLat mode0600, flushed to disk viafsync, and atomically replaced viarename. No partial files, race conditions, or unencrypted leaks.Directory Hardening: Auth directories are verified at mode
0700and tightened immediately if found looser.Local Proxy Binding:
npm run authbinds strictly to127.0.0.1, never exposing authentication cookies to external network interfaces.Git Safety:
.auth-data/, cookies, and tokens are permanently ignored in.gitignore.Dependency Pinning: Enforces
alexa-cookie2 >= 5.0.4to avoid Amazon400 InvalidTokenrefresh regressions.
Project Structure
alexa-mcp/
├── src/
│ ├── index.ts # MCP Stdio server entrypoint & factory
│ ├── index.js # Backward-compatibility shim (forwards to dist/)
│ ├── alexa-client.ts # Typed wrapper around the Alexa remote client with atomic auth
│ ├── alexa-remote/ # Native TypeScript Alexa Remote engine & HTTP/2 push listener
│ ├── tools.ts # 32 MCP tool registrations with Zod schemas
│ ├── server.ts # Streamable HTTP & SSE Express server
│ ├── auth.ts # Interactive proxy login flow
│ └── types/
│ └── alexa.ts # Domain interfaces (AuthData, Devices, Groups, etc.)
├── dist/ # Compiled JavaScript, TypeScript declarations & maps
├── test/
│ ├── alexa-remote.test.ts # Native Alexa Remote engine unit tests
│ ├── tools.test.ts # In-memory tests for all 32 tools & schemas
│ ├── stdio-transport.test.ts # Subprocess stdio JSON-RPC handshake tests
│ ├── server-transport.test.ts # Express Streamable HTTP & SSE transport tests
│ └── auth-storage.test.ts # File mode (0600/0700) & atomic write security tests
├── docs/
│ ├── ARCHITECTURE.md # Architectural deep dive & protocol mechanics
│ └── TESTING.md # Comprehensive test strategy & execution guide
├── .auth-data/ # Git-ignored local credentials store (mode 0700)
│ └── auth.json # Session cookies & device registration (mode 0600)
├── CHANGELOG.md # Detailed release and migration history
├── package.json # Package manifest & build scripts
├── tsconfig.json # TypeScript compiler configuration (ES2022/NodeNext)
├── LICENSE # MIT License
└── README.md # Project documentationAcknowledgments
The Model Context Protocol team at Anthropic.
License
MIT © James Tucker
Available Tools
32 toolsalexa_add_list_itemAdd Item to ListB
Add an item to an Alexa list (shopping, to-do, etc).
Inputs: value (required), listId (required).
alexa_announceSend Alexa AnnouncementB
Send a voice announcement to a specific Echo device. The message will be spoken aloud.
Inputs: message (required), serialNumber (required).
alexa_create_groupCreate Smart Home GroupA
Create a new Alexa smart home group/room with a name and optional list of appliance IDs.
Inputs: name (required), applianceIds.
alexa_curated_ttsSpeak Curated PhraseA
Make Alexa speak a randomized built-in phrase from a curated category.
Inputs: category (required), serialNumber (required).
alexa_delete_groupDelete Smart Home GroupB
Delete an Alexa smart home group/room.
Inputs: groupId (required).
alexa_do_not_disturbSet Do Not DisturbA
Enable or disable Do Not Disturb on a specific Echo device.
Inputs: enabled (required), serialNumber (required).
alexa_execute_routineExecute Alexa RoutineA
Execute an existing Alexa routine by providing its automation definition (from alexa_list_routines).
Inputs: routine (required).
alexa_fire_tv_controlControl Fire TV DeviceB
Control a Fire TV or Fire TV Cube (turnOn, turnOff, pause, resume, navigateHome).
Inputs: command (required), serialNumber (required).
alexa_get_historyGet Alexa Voice HistoryA
Retrieve recent voice interaction history (what users said to Alexa, device used, timestamps).
Inputs: limit.
alexa_get_list_itemsGet List ItemsA
Get all items from a specific Alexa list.
Inputs: listId (required).
alexa_get_notificationsGet Alarms, Timers & RemindersA
List active alarms, timers, and reminders across all Echo devices in the account.
Inputs: type.
alexa_get_volumesGet All Device VolumesA
Get the current volume levels of all Echo devices.
Inputs: no named parameters.
alexa_list_devicesList Alexa DevicesA
List all Amazon Echo devices in your account with their serial numbers, types, and online status.
Inputs: no named parameters.
alexa_list_groupsList Smart Home GroupsA
List all smart home groups/rooms configured in Alexa. Shows which devices are assigned to each group.
Inputs: no named parameters.
alexa_list_listsList Alexa ListsA
Get all Alexa lists (shopping lists, to-do lists, custom lists).
Inputs: no named parameters.
alexa_list_routinesList Alexa RoutinesA
List all Alexa routines configured in the account. Shows routine names, triggers, and actions.
Inputs: no named parameters.
alexa_list_smarthome_devicesList Smart Home DevicesB
List all smart home devices registered in Alexa (lights, switches, sensors, etc).
Inputs: no named parameters.
alexa_media_controlControl Media PlaybackC
Control media playback (stop, pause, play, next, previous) on a specific Echo or all devices.
Inputs: action (required), serialNumber (required).
alexa_play_audiblePlay Audiobook via AudibleB
Play an audiobook from Audible on an Echo device.
Inputs: searchPhrase (required), serialNumber (required).
alexa_play_behaviorPlay Native Routine BehaviorB
Trigger native routine behaviors like weather report, traffic update, flash briefing, jokes, fun facts, or stories.
Inputs: behavior (required), serialNumber (required).
alexa_play_musicPlay Music via Streaming ProviderA
Search and stream music on an Echo device from Amazon Music, Spotify, Apple Music, TuneIn, iHeartRadio, or Deezer.
Inputs: searchPhrase (required), serialNumber (required), provider.
alexa_play_soundPlay Built-in Sound EffectA
Play a built-in sound effect or chime on an Echo device (e.g. bells, doorbells, boings, applause, buzzers).
Inputs: soundId (required), serialNumber (required).
alexa_query_deviceQuery Smart Home DeviceA
Query the current state of one or more smart home devices (on/off, brightness, temperature, etc).
Inputs: entityIds (required).
alexa_set_alarm_volumeSet Alarm & Notification VolumeA
Adjust alarm and notification volume level independently from media/music volume.
Inputs: volume (required), serialNumber (required).
alexa_set_equalizerSet Device EqualizerA
Adjust bass, midrange, and treble levels on an Echo speaker (-6 to +6 dB).
Inputs: bass (required), treble (required), midrange (required), serialNumber (required).
alexa_set_reminderSet Spoken ReminderA
Schedule a spoken reminder on an Echo device at a specific time.
Inputs: text (required), timestamp (required), serialNumber (required).
alexa_set_volumeSet Device VolumeA
Set the volume of a specific Echo device (0-100).
Inputs: volume (required), serialNumber (required).
alexa_smarthome_actionExecute Smart Home Device ActionA
Control Alexa smart home devices directly (turn on/off, set brightness, set temperature, lock/unlock).
Inputs: action (required), entityId (required), value, entityType.
alexa_speakSpeak TextA
Make Alexa speak plain text directly on a specific Echo device using native text-to-speech (no announcement chime).
Inputs: text (required), serialNumber (required).
alexa_speak_ssmlSpeak SSMLC
Make Alexa speak using SSML (Speech Synthesis Markup Language) for advanced voice control.
Inputs: ssml (required), serialNumber (required).
alexa_text_commandSend Text Command to AlexaB
Send a text command to Alexa as if you spoke it. Example: "turn on the kitchen lights"
Inputs: command (required), serialNumber (required).
alexa_update_groupUpdate Smart Home GroupA
Update an existing Alexa smart home group/room. Sets the name and full list of appliance IDs.
Inputs: name (required), groupId (required), applianceIds (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools target distinct resources/actions (devices, groups, routines, media, lists), and descriptions clarify edge cases like speak vs announce vs speak_ssml. However, the number of voice/content-related tools (speak, announce, curated_tts, play_behavior, play_sound, play_music) could still cause occasional misselection.
All tools share the alexa_ prefix and snake_case format, with most following a verb_noun pattern (alexa_set_volume, alexa_list_routines, alexa_delete_group). A few exceptions like alexa_text_command, alexa_curated_tts, and alexa_fire_tv_control break the strict pattern but remain readable and predictable.
With 32 tools, this is a very large surface for an MCP server. While the scope is broad, the count exceeds what most agents need and adds selection friction; several tools could likely be consolidated or omitted.
The server covers a wide range of Alexa capabilities: voice output, smart home control, groups, routines, lists, media, alarms/reminders, device settings, and history. Minor gaps exist (e.g., messaging/calling, skill management, multi-room audio), but core Alexa workflows are well represented.
Maintenance
Related MCP Connectors
Skills, agents and memory in the cloud, plus a gateway to your other MCP servers.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to control Alexa-connected smart home devices, including voice announcements, music control, smart lighting, sensor monitoring, and volume management through the Alexa API.1-
- AlicenseAqualityBmaintenanceAn MCP server that lets LLMs control Amazon Alexa devices, including announcements, text commands, smart-home group management, routines, and list operations.188MIT
- AlicenseBqualityCmaintenanceEnables MCP-compatible LLMs to control Amazon Alexa devices by sending announcements, text commands, and SSML speech, as well as managing smart-home groups, routines, lists, volume, Do Not Disturb, and sensor queries.19MIT
- AlicenseNot gradedqualityCmaintenanceEnables Alexa+ voice agents to control smart home devices, generate daily briefings, orchestrate routines, and query user context through tools backed by AWS Bedrock.1MIT