alexa-mcp
This project was developed and is maintained by AI (Claude Code). Use at your own discretion.
An MCP server for Amazon Alexa: list and control Echo speakers, Echo Shows and Fire TVs, make Alexa speak or announce, run routines, read and control the smart-home devices Alexa knows about (thermostats, lights, plugs, locks, garage doors, robot vacuums, scenes), read and edit shopping/to-do lists, and set or cancel alarms, timers and reminders.
It talks to Amazon's private Alexa web API — the one the Alexa app uses — through alexa-remote2. There is no public API for any of this, so expect occasional breakage when Amazon changes things.
Sign in once
You sign in to Amazon in your own browser; this server never sees your password.
- In a chat: ask Claude to sign in to Alexa. It calls
alexa_begin_login and gives you an amazon.com link. Sign in there (password, two-step code, whatever Amazon asks), and you land on a blank www.amazon.com/ap/maplanding page. Paste that page's address back and Claude calls alexa_finish_login.
- Hosted connector: the sign-in page shows a Sign in to Amazon button and a box for that same address.
- Terminal:
npx @chrischall/alexa-mcp login prints the link and reads the pasted address (--print also writes the registration as one base64 line for ALEXA_REGISTRATION; treat it as a credential).
Under the hood this is the Alexa iOS app's OAuth sign-in with PKCE. The link carries only a challenge, the matching secret stays on the server, and the code in the pasted address is single-use and expires in minutes. Finishing registers a virtual device named alexa-mcp on your account and saves the registration (refresh token plus session cookies) to ~/.alexa-mcp/registration.json (mode 0600). After that no browser is needed: cookies are re-minted from the refresh token every few days. To revoke access, remove the alexa-mcp device from your Amazon account (Manage Your Content and Devices → Devices). A copy of the token is written to registration-seed.json while sign-in completes and deleted once registration.json is saved. Versions before this fix never deleted it, so if you are cleaning up an older install, delete ~/.alexa-mcp/registration-seed.json too.
Tools
| Tool | What it does |
|---|
alexa_list_devices | Echo speakers, Echo Shows, Fire TVs and other Alexa devices with online status (not thermostats, lights or plugs: those are smart-home) |
alexa_get_now_playing | Media state on one device |
alexa_list_volumes | Volume and mute (only devices Amazon reports, often just a few) |
alexa_get_do_not_disturb | Which devices have Do Not Disturb on |
alexa_get_equalizer | Bass / mid / treble of a speaker or soundbar |
alexa_list_bluetooth | Bluetooth devices paired with each Echo, and what's streaming |
alexa_list_routines | Routines with their triggers |
alexa_list_smart_home | Thermostats, lights, plugs, locks, sensors, groups and scenes, with the actions this server can send to each |
alexa_get_smart_home_state | Live state: thermostat temperature, mode and setpoints, humidity, light on/brightness/colour, lock state, sensors, reachability |
alexa_list_lists / alexa_get_list_items | Shopping and to-do lists |
alexa_list_alarms_reminders | Alarms, timers and reminders (with ids for cancelling) |
alexa_set_volume ✋ | Set a device's volume |
alexa_playback ✋ | Play / pause / next / previous |
alexa_stop ✋ | Stop one device (or all of them): music, a ringing alarm, speech |
alexa_speak ✋ | Speak on one device, or announce on several |
alexa_run_builtin ✋ | Play weather, traffic, the news briefing, a joke, a story, calendar and other built-ins out loud |
alexa_fire_tv ✋ | Fire TV on / off / pause / resume / home |
alexa_set_do_not_disturb ✋ | Do Not Disturb on or off |
alexa_set_equalizer ✋ | Set bass / mid / treble |
alexa_run_routine ✋ | Run a routine now |
alexa_control_smart_home ✋ | turnOn / turnOff / setBrightness / setColor / setColorTemperature / sceneActivate |
alexa_list_device_modes | A device's mode settings (thermostat fan mode, vacuum mode, light effect), current value and options |
alexa_set_device_mode ✋ | Change one of those modes, e.g. fan mode to Circulate (not garage doors) |
alexa_lock ✋ | Lock or unlock a smart lock. Unlocking reduces security; Amazon may insist on a voice PIN or the Alexa app |
alexa_garage_door ✋ | Open or close a garage door. Opening reduces security |
alexa_set_thermostat ✋ | Thermostat setpoint(s) and/or mode, checked against the thermostat's allowed range |
alexa_set_vacation_mode ✋ | Thermostat vacation / away mode, emulated: saves each thermostat's settings, sets energy-saving setpoints, and restores them when turned off |
alexa_create_reminder ✋ / alexa_create_timer ✋ / alexa_cancel_alarm_reminder ✋ | Set a reminder, alarm or timer; cancel one |
alexa_add_list_item ✋ / alexa_update_list_item ✋ / alexa_remove_list_item ✋ | Edit a list: add, check off / un-check, delete |
alexa_begin_login / alexa_finish_login | Browser sign-in (see above) |
alexa_session_status | Configuration, no network |
alexa_healthcheck | Does Amazon still accept the session? |
✋ = confirmation-gated. A client that supports prompts asks you first; elsewhere (claude.ai, Claude Desktop) the first call sends nothing and returns a preview plus a confirmToken, and only a repeat call with that token acts.
Deliberately left out:
- Free-text voice commands ("Alexa, …", the library's
textCommand). They can buy things and unlock doors without going through a specific, confirm-gated tool, so no tool sends one.
Unlocking a door and opening a garage door are possible, but only through alexa_lock and alexa_garage_door, which are marked destructive and always confirmation-gated.
Vacation mode is an emulation. The Alexa app's own thermostat Vacation Mode is not reachable through the API this server uses (its thermostat modes are only HEAT / COOL / AUTO / OFF), so this does not flip the app's toggle. Instead alexa_set_vacation_mode saves each thermostat's mode and setpoints to ~/.alexa-mcp/vacation.json (mode 0600) before it changes anything, then sets heat-to 55° / cool-to 85° (or what you ask for). Thermostats that are OFF stay OFF. Turning it off restores the saved settings. Turning it on twice is refused, so the originals are never overwritten.
Configuration
| Variable | Default | Purpose |
|---|
ALEXA_REGISTRATION | — | Registration JSON, or the base64 line from login --print. Optional when the state file exists. If it is malformed but the state file is valid, the state file is used and a warning is logged. |
ALEXA_STATE_DIR | ~/.alexa-mcp | Where registration.json and pending sign-ins live. |
ALEXA_AMAZON_PAGE | amazon.com | Amazon site of the account (or what the registration recorded). |
ALEXA_ACCEPT_LANGUAGE | en-US | Accept-Language sent to Amazon. |
MCP_CONFIRM_MODE | ask-user | ask-user / auto / refuse — whether the model must get your approval in chat before using a confirmToken. |
MCP_CONFIRM_ELICITATION | on | off skips the confirmation prompt even on clients that declare support. |
When both ALEXA_REGISTRATION and the state file are present, whichever has the newer tokenDate wins, whatever device it belongs to (a tie goes to the state file, the refreshed copy). So a re-login through alexa_finish_login survives a restart even with an older ALEXA_REGISTRATION still set, and a freshly pasted ALEXA_REGISTRATION beats an old state file.
Upgrading from 0.1
0.2.0 changed how the connector signs in. The pasted ALEXA_REGISTRATION field is replaced by the browser sign-in flow (auth.flow in mint.yaml: a Sign in to Amazon link, then paste the address you land on). Existing hosted registrations must switch to the new flow: sign in once more through it. alexa-mcp login --port <n> is no longer needed: the flag is ignored with a notice, since the sign-in now happens in your own browser.
Hosting
mint.yaml describes the server to mcp-host: one child per user (identity.perUserChild), a two-step auth.flow (begin → sign in on amazon.com → paste the address), and the registration persists in each user's data dir.
Development
npm install
npm test # typecheck + vitest (no network)
npm run build # tsc + esbuild bundle (dist/bundle.js is the .mcpb entry)
See docs/ALEXA-API.md for the verified response shapes and hosts.