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.

Built on top of alexa-remote2 (the actively maintained client for Amazon's Alexa API) 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  │
                     └───────────────────────────────┘

1. 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.

2. Streamable HTTP & SSE Server (src/server.ts / dist/server.js): High-performance Express server supporting the modern MCP Streamable HTTP specification (POST /mcp or POST /) as well as Legacy SSE (GET /sse with POST /messages). Includes CORS headers and session management, ideal for remote LLMs, Perplexity, Open WebUI, and Cloudflare Tunnels.

Related MCP server: Home Assistant MCP Server

Features (19 Tools)

Every tool is strictly typed with Zod schema validation and comprehensive error handling:

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-Tucke-r/alexa-mcp.git
cd alexa-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run automated tests
npm test

Authentication

Amazon's Alexa API is private and requires a browser-based login. The server includes an interactive authentication helper:

npm run auth

What npm run auth does:

1. Starts a secure local HTTP proxy on 127.0.0.1:3457 (automatically opens your default browser on macOS).

2. You log in to your Amazon account securely. Handles 2FA / OTP seamlessly because it proxies Amazon's real authentication pages.

3. The proxy captures both the session cookies and the device registration (macDms) Amazon issues.

4. Credentials are automatically saved to .auth-data/auth.json with owner-only permissions (0600, directory 0700).

You only need to run this once. alexa-remote2 refreshes the token automatically during normal operation.

Why manual cookie pasting is unsupported:

alexa-remote2 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 auth

Each 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.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Backward Compatibility: Existing configurations pointing to /Users/jtucker/src/alexa-mcp/src/index.js continue 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 list

3. Streamable HTTP / SSE Server (Remote Clients & Web UIs)

Run the server:

# Production
npm run serve

# Development (hot reload)
npm run serve:dev

By default, the server listens on 0.0.0.0:8000 (configurable via PORT environment variable):

• Streamable HTTP Endpoint (Recommended): http://localhost:8000/mcp or http://localhost:8000/

• Legacy SSE Endpoint: http://localhost:8000/sse (messages at POST /messages)

Configure in remote MCP clients (e.g., Perplexity, Open WebUI, LibreChat):

{
  "mcpServers": {
    "alexa": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Environment Variables

Development & Scripts

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 test

Test Coverage (19 Tests across 4 Suites):

1. test/tools.test.ts:

   • In-memory MCP client/server integration.

   • Verifies registration, schemas, and descriptions for all 19 tools.

   • Tests mock execution of every device, routine, smart home, audio, and list tool.

   • Verifies Zod input validation (e.g. volume out-of-bounds rejection).

   • Tests error handling when the upstream Alexa API fails.

2. test/stdio-transport.test.ts:

   • Spawns subprocesses over actual stdin/stdout pipes.

   • Tests MCP initialize and tools/list handshakes on src/index.js (backward-compat shim).

   • Tests MCP handshakes on dist/index.js (compiled binary).

   • Verifies JSON-RPC error codes on unrecognized methods (-32601).

3. 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 /mcp stateful sessions.

   • Tests SSE GET /sse streams.

   • Tests automatic Accept header normalization (application/json, text/event-stream).

4. test/auth-storage.test.ts:

   • Atomic file write verification (temp file -> sync -> atomic rename).

   • File permission verification (0600 for auth.json, 0700 for 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.json are written to a unique temporary file opened with O_CREAT | O_EXCL at mode 0600, flushed to disk via fsync, and atomically replaced via rename. No partial files, race conditions, or unencrypted leaks.

• Directory Hardening: Auth directories are verified at mode 0700 and tightened immediately if found looser.

• Local Proxy Binding: npm run auth binds strictly to 127.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.4 to avoid Amazon 400 InvalidToken refresh 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 alexa-remote2 with atomic auth
│   ├── tools.ts              # 19 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/
│   ├── tools.test.ts         # In-memory tests for all 19 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 documentation

Acknowledgments

• Renato Ascencio for authoring the original alexa-mcp project.

• Apollon77 for maintaining alexa-remote2, which powers communication with Amazon's private Alexa endpoints.

• The Model Context Protocol team at Anthropic.

License

MIT © Renato Ascencio, James Tucker