alexa-mcp

alexa-mcp

このプロジェクトは AI（Claude Code）によって開発・保守されています。ご自身の判断でご利用ください。

Amazon Alexa 用の MCP サーバーです。Echo スピーカー、Echo Show、Fire TV の一覧表示と操作、Alexa に音声を再生・アナウンスさせる操作、ルーティンの実行、Alexa が認識しているスマートホームデバイス（サーモスタット、照明、プラグ、ロック、ガレージドア、ロボット掃除機、シーン）の読み取りと操作、買い物リスト／ToDo リストの読み取りと編集、アラーム、タイマー、リマインダーの設定とキャンセルができます。

Alexa アプリが使用している Amazon の非公開Alexa Web API と、alexa-remote2 を通じて通信します。これらの機能に公開 API はないため、Amazon による変更で動作しなくなることがあります。

一度だけサインイン

Amazon にはご自身のブラウザーでサインインします。このサーバーがパスワードを受け取ることはありません。

• チャットの場合： Claude に Alexa へのサインインを依頼します。Claude は alexa_begin_login を呼び出し、amazon.com のリンクを提示します。そのリンクからサインイン（パスワード、2 段階認証コードなど、Amazon が求めるもの）すると、空白の www.amazon.com/ap/maplanding ページが表示されます。そのページのアドレスを貼り付けると、Claude が alexa_finish_login を呼び出します。
• ホスト型コネクターの場合： サインインページにSign in to Amazonボタンと、同じアドレスを貼り付ける入力欄が表示されます。
• ターミナルの場合： npx @chrischall/alexa-mcp login を実行すると、リンクが表示され、貼り付けたアドレスが読み込まれます（--print を指定すると、登録情報が ALEXA_REGISTRATION 用の 1 行の base64 形式でも出力されます。これは認証情報として取り扱ってください）。

内部では、Alexa iOS アプリの OAuth サインインで PKCE を使用しています。リンクに含まれるのはチャレンジのみで、一致するシークレットはサーバー上に保持されます。貼り付けたアドレスに含まれるコードは 1 回限り有効で、数分で期限切れになります。サインインを完了すると、アカウントに alexa-mcp という名前の仮想デバイスが登録され、登録情報（リフレッシュトークンとセッション Cookie）が ~/.alexa-mcp/registration.json（モード 0600）に保存されます。以降はブラウザーは不要です。Cookie は数日ごとにリフレッシュトークンから再生成されます。アクセスを取り消すには、Amazon アカウントの「コンテンツと端末の管理」→「端末」から alexa-mcp デバイスを削除してください。サインインの完了中はトークンのコピーが registration-seed.json に書き込まれ、registration.json の保存後に削除されます。この修正より前のバージョンでは削除されなかったため、古いインストールを整理する場合は ~/.alexa-mcp/registration-seed.json も削除してください。

ツール

ツール	機能
alexa_list_devices	Echo スピーカー、Echo Shows、Fire TV などの Alexa デバイスとオンライン状態（サーモスタット、ライト、プラグは対象外です。これらはスマートホームに含まれます）
alexa_get_now_playing	1 台のデバイスのメディア状態
alexa_list_volumes	音量とミュート状態（Amazon が報告するデバイスのみで、多くの場合は数台だけです）
alexa_get_do_not_disturb	おやすみモードがオンになっているデバイス
alexa_get_equalizer	スピーカーまたはサウンドバーの低音／中音／高音
alexa_list_bluetooth	各 Echo とペアリングされた Bluetooth デバイスと、ストリーミング中の内容
alexa_list_routines	トリガーを含むルーティン
alexa_list_smart_home	サーモスタット、ライト、プラグ、ロック、センサー、グループ、シーンと、このサーバーがそれぞれに送信できるアクション
alexa_get_smart_home_state	ライブ状態：サーモスタットの温度、モード、設定温度、湿度、ライトのオン／明るさ／色、ロックの状態、センサー、接続状態
alexa_list_lists / alexa_get_list_items	買い物リストと ToDo リスト
alexa_list_alarms_reminders	アラーム、タイマー、リマインダー（キャンセル用の ID 付き）
alexa_set_volume ✋	デバイスの音量を設定します
alexa_playback ✋	再生／一時停止／次へ／前へ
alexa_stop ✋	1 台またはすべてのデバイスで、音楽、鳴動中のアラーム、音声を停止します
alexa_speak ✋	1 台のデバイスで発話するか、複数台にアナウンスします
alexa_run_builtin ✋	天気、交通情報、ニュースブリーフィング、ジョーク、ストーリー、カレンダーなどの組み込み機能を音声で再生します
alexa_fire_tv ✋	Fire TV のオン／オフ／一時停止／再開／ホーム
alexa_set_do_not_disturb ✋	おやすみモードをオンまたはオフにします
alexa_set_equalizer ✋	低音／中音／高音を設定します
alexa_run_routine ✋	ルーティンを今すぐ実行します
alexa_control_smart_home ✋	turnOn / turnOff / setBrightness / setColor / setColorTemperature / sceneActivate
alexa_list_device_modes	デバイスのモード設定（サーモスタットのファンモード、掃除機のモード、ライトのエフェクト）、現在の値と選択肢
alexa_set_device_mode ✋	これらのモードのいずれかを変更します（例：ファンモードを Circulate に変更。ガレージドアは対象外です）
alexa_lock ✋	スマートロックを施錠または解錠します。解錠するとセキュリティが低下します。Amazon から音声 PIN または Alexa アプリの使用を求められる場合があります
alexa_garage_door ✋	ガレージドアを開閉します。開くとセキュリティが低下します
alexa_set_thermostat ✋	サーモスタットの設定温度および／またはモードを設定します。サーモスタットで許可されている範囲と照合されます
alexa_set_vacation_mode ✋	サーモスタットの休暇／外出モードをエミュレートします。各サーモスタットの設定を保存し、省エネ設定温度に変更して、オフにすると元に戻します
alexa_create_reminder ✋ / alexa_create_timer ✋ / alexa_cancel_alarm_reminder ✋	リマインダー、アラーム、タイマーを設定します。またはキャンセルします
alexa_add_list_item ✋ / alexa_update_list_item ✋ / alexa_remove_list_item ✋	リストを編集します：項目の追加、チェック／チェック解除、削除
alexa_begin_login / alexa_finish_login	ブラウザーでサインインします（上記を参照）
alexa_session_status	ネットワークを使わない設定確認
alexa_healthcheck	Amazon が引き続きセッションを受け入れているかを確認します

✋ = 確認が必要です。 プロンプトに対応したクライアントでは、最初に確認を求めます。それ以外（claude.ai、Claude Desktop）では、最初の呼び出しは何も送信せず、プレビューと confirmToken を返します。そのトークンを付けて再度呼び出すと実行されます。

意図的に対象外とした機能：

• 自由形式の音声コマンド（「Alexa、…」、ライブラリの textCommand）。特定の確認必須ツールを介さずに商品を購入したりドアを解錠したりできるため、音声コマンドを送信するツールはありません。

ドアの解錠とガレージドアを開く操作は可能ですが、alexa_lock と alexa_garage_door のみを通じて実行でき、破壊的操作としてマークされ、必ず確認が必要です。 Vacation modeはエミュレーションです。 Alexaアプリ独自のサーモスタットのVacation Modeは、このサーバーが使用するAPIからは利用できません（サーモスタットのモードはHEAT／COOL／AUTO／OFFのみです）。そのため、アプリの切り替えボタンは操作されません。代わりに、alexa_set_vacation_modeは何かを変更する前に、各サーモスタットのモードと設定温度を~/.alexa-mcp/vacation.json（モード0600）に保存し、その後、暖房設定温度を55°／冷房設定温度を85°（または指定した温度）に設定します。OFFになっているサーモスタットはOFFのままです。オフにすると、保存した設定が復元されます。2回続けてオンにすることはできないため、元の設定が上書きされることはありません。

設定

変数	デフォルト	用途
ALEXA_REGISTRATION	—	登録JSON、またはlogin --printで表示されるbase64の行です。状態ファイルが存在する場合は省略できます。不正な形式でも状態ファイルが有効であれば、状態ファイルが使用され、警告がログに記録されます。
ALEXA_STATE_DIR	~/.alexa-mcp	registration.jsonと保留中のサインイン情報を保存する場所です。
ALEXA_AMAZON_PAGE	amazon.com	アカウントのAmazonサイト（または登録情報に記録されたサイト）です。
ALEXA_ACCEPT_LANGUAGE	en-US	Amazonに送信するAccept-Languageです。
MCP_CONFIRM_MODE	ask-user	ask-user／auto／refuse — confirmTokenを使用する前に、チャットでモデルがユーザーの承認を得る必要があるかどうかを指定します。
MCP_CONFIRM_ELICITATION	on	offにすると、サポートを宣言しているクライアントでも確認プロンプトが省略されます。

ALEXA_REGISTRATIONと状態ファイルの両方が存在する場合は、どちらのデバイスに属するかにかかわらず、tokenDateが新しい方が優先されます（同じ場合は、更新されたコピーである状態ファイルが優先されます）。そのため、古いALEXA_REGISTRATIONが設定されたままでも、alexa_finish_loginで再ログインした情報は再起動後も維持されます。また、新たに貼り付けたALEXA_REGISTRATIONは、古い状態ファイルより優先されます。

0.1からのアップグレード

0.2.0では、コネクターのサインイン方法が変更されました。貼り付けていたALEXA_REGISTRATIONフィールドは、ブラウザーのサインインフロー（mint.yamlのauth.flow：Amazonにサインインリンクをクリックし、移動先のアドレスを貼り付ける）に置き換えられました。既存のホスト登録では、新しいフローに切り替える必要があります。このフローからもう一度サインインしてください。サインインはご自身のブラウザーで行うようになったため、alexa-mcp login --port <n>は不要です。このフラグは通知とともに無視されます。

ホスティング

mint.yamlでは、mcp-host向けにサーバーを定義しています。ユーザーごとに1つの子プロセス（identity.perUserChild）、2段階のauth.flow（開始 → amazon.comでサインイン → アドレスを貼り付け）、および各ユーザーのデータディレクトリへの登録情報の保存を指定しています。

開発

npm install
npm test          # typecheck + vitest (no network)
npm run build     # tsc + esbuild bundle (dist/bundle.js is the .mcpb entry)

検証済みのレスポンス形式とホストについては、docs/ALEXA-API.mdを参照してください。