kiaaccess-mcp

Kia Access MCP

Kia Access モバイルアプリが使用する Kia Owners API を通じて、Claude をお使いの Kia 車両に接続する Model Context Protocol サーバーです。車両の状態、位置、走行距離計、EV の充電状態に加え、確認後に実行されるドア、空調、充電のコマンドを利用できます。

警告

AI によって開発されたプロジェクトです。 このコードベースは Claude Code によって構築、保守されています。実装を監査した人間はいません。実車に接続する前に、コードとツールの権限を確認してください。

注意

このサーバーは、2 トンの物体を動かしたり、車のロックを解除したりできます。 すべてのコマンドツールは実行前に確認を求めます。クライアントが対応している場合は確認プロンプトを表示し、対応していない場合はプレビューと、再度の呼び出しでのみ使用できる一度限りのトークンを提示します（確認を参照）。また、KIA_WRITE_MODE=all を指定しない限り、ドアのロック／ロック解除機能は登録されません。設定を変更する前に、車両コマンドをお読みください。

できること

Claude に次のように尋ねられます。

• 「EV9 はロックされていますか？ 充電残量はどのくらいですか？」
• 「車内を 72 度にして、10 分間暖めて」
• 「車をどこに停めましたか？」
• 「車の状態を更新してから、走行距離計を教えて」

必要条件

• Node.js 22.5 以降
• 車両を登録済みの Kia Owners／Kia Access アカウントと、そのパスワード
• 一度だけ使用する MFA パスコードを確認できる携帯電話またはメールボックス

利用条件への同意

このサーバーを使用すると、以下に同意したものとみなされます。

1. ご自身の Kia アカウント認証情報を使用して、Kia Access アプリと同じ非公開 API に接続します。他の人の車両やアカウントにはアクセスできません。
2. 利用には Kia の規約が適用されます。 アプリを使用する場合と同様です。これは公式またはサポート対象の連携ではなく、Kia との提携、Kia による推奨、または Kia の後援を受けたものではありません。
3. コマンドは現実世界の車両に作用します。 ロックを解除すると、誰かがロックするまで車は無防備な状態になります。空調の事前作動では HVAC が動作し、電力を消費します。確認したすべてのコマンドについて、利用者が責任を負います。
4. ログイン失敗には取り返しのつかない影響があります。 Kia は失敗回数をカウントし（loginAttempt）、最終的に enforceRecaptcha を設定します。その後、そのアカウントではサーバー側からログインできなくなります。そのため、このサーバーは拒否された認証情報を再試行しません。ログインに失敗した場合を参照してください。

インストール

1. クローンしてビルドする

git clone https://github.com/chrischall/kiaaccess-mcp.git
cd kiaaccess-mcp
npm install
npm run build

2. 認証情報を設定する

cp .env.example .env
# Edit .env: KIA_USERNAME, KIA_PASSWORD (and optionally KIA_WRITE_MODE,
#            KIA_DEVICE_ID, KIA_RMTOKEN, KIA_REQUEST_TIMEOUT_MS — see .env.example)

.env は Git の追跡対象外です。サーバーが認証情報をログに記録することはなく、ツールがパスワードを返すこともありません。

3. Claude Code に登録する

{
  "mcpServers": {
    "kiaaccess": {
      "command": "npx",
      "args": ["-y", "kiaaccess-mcp"],
      "env": {
        "KIA_USERNAME": "[email protected]",
        "KIA_PASSWORD": "your-password",
        "KIA_WRITE_MODE": "comfort"
      }
    }
  }
}

認証情報がなくてもサーバーの起動は妨げられません。サーバーは起動して tools/list に応答し、ツールが Kia への接続を必要としたときにのみ設定エラーを報告します。kia_session_status を実行すると、サーバーが認識している状態を確認できます。

MFA の初回セットアップ

Kia は新しいデバイスごとにワンタイムパスコードを要求します。このサーバーは初回のみセットアップを行い、生成されたログイン状態維持トークン（rmtoken）を ~/.kiaaccess-mcp/session.json に保存します。それ以降は新しいセッションを自動で発行します。Kia はトークンをローテーションせず、再度チャレンジすることもありません。

Claude を通じて、次の順に実行します。

1. kia_session_status — 認証情報が設定されていることを確認します。hasSession: false と表示された場合は続行します。
2. kia_start_login（最初に確認を求めます）— 認証情報を送信し、otpKey と xid、さらに Kia に登録されている電話番号／メールアドレスのマスク済み表示を返します。
3. kia_send_otp — SMS または EMAIL を選びます。パスコードの有効期限は約 2 分です。
4. kia_verify_otp — パスコードを渡します。トークンはローカルに保存され、意図的に返されません。
5. kia_list_vehicles — セッションが機能することを確認し、他のすべてのツールで必要となる vehicleKey（vehicle_key 引数として指定）を取得します。

やり直す場合（トークンの失効、パスワードの変更、マシンの引き渡しなど）は、kia_forget_session（最初に確認を求めます）を実行し、ステップ 2 から繰り返します。

OTP を確認できる電話がない場所で実行する場合

初回セットアップには、人間による操作が一度必要です。OTP を確認できる人がいないデプロイ環境（リモートホスト）ではセットアップできないため、対応できるマシンでセットアップしてからトークンを移します。

1. 両方のマシンで、セットアップの前に KIA_DEVICE_ID を固定の UUID に設定します。rmtoken はデバイス UUID に紐付けて生成されるため、別の UUID では使えません。また、kia_session_status が報告するのは常に切り詰められたプレフィックスのみです。自動生成させてしまうと、必要な値を後から読み取れません。
2. 上記の手順でセットアップした後、ターミナルで ~/.kiaaccess-mcp/session.json から rmtoken の値を自分でコピーします。どのツールもこの値を返しません。このトークンは長期間有効な MFA 回避手段であるため、会話に出力されることはありません。
3. リモートのデプロイ環境に、その値を KIA_RMTOKEN として設定し、KIA_USERNAME、KIA_PASSWORD、同じ KIA_DEVICE_ID も設定します。

KIA_RMTOKEN はローカルのセッションストアの内容より優先されるため、デプロイ環境のセッションには、最後に書き込まれた値ではなく、渡した値が使われます。この値は代わりに使われるパスワードと同様に扱ってください。MFA を回避でき、アカウントのパスワードと組み合わせると車両を完全に制御できます。

ログインに失敗した場合

再試行しないでください。拒否されるたびに Kia は loginAttempt を増やし、最終的には enforceRecaptcha を設定します。これにより、そのアカウントのサーバー側ログインが恒久的に機能しなくなります。まず Kia Access アプリでメールアドレスとパスワードを確認し、.env を修正して再起動してから、もう一度試してください。

車両コマンド

KIA_WRITE_MODE は、どのコマンドツールを登録するかを決定します。これは構造上のゲートであり、実行時のチェックではありません。登録されていないツールは、ホストの権限設定でも、会話に挿入された指示でも呼び出せません。

KIA_WRITE_MODE	登録されるツール
none	読み取りツールとアカウントツールのみ
comfort (デフォルト)	空調の開始／停止と充電コマンド
all	さらに kia_lock_doors と kia_unlock_doors

認識されない値は安全側に倒して none として扱われ、標準エラーに警告が出力されます。入力ミスによって車のロック解除機能が意図せず有効になることはありません。

すべてのコマンドには、次の 2 つのルールも適用されます。

• 確認が必要です。 確認するまで、何も送信されません。確認画面には送信される正確なリクエストが表示されます。確認が済むまではネットワーク呼び出しも一切行われません。確認を参照してください。
• 受け付けられても、実行確認ではありません。 Kia からの「success」という応答は、リクエストが受け付けられたことしか意味しません。コマンドが反映されたと確認する唯一の方法は、車両情報を再取得して該当フィールドの差分を確認することです。そのため、結果では commandAccepted と stateConfirmed を別々に報告します。変化が確認されるまでに 30～60 秒かかりました。

確認

すべての書き込みツール（上記のコマンドに加え、kia_start_login と kia_forget_session）は、実行前に確認を求めます。確認プロンプトを表示できるクライアント（Claude Code）では、リクエストの内容がそのまま表示されます。表示できないクライアント（claude.ai、Claude Desktop）では、代わりに2段階のフローが実行されます。最初の呼び出しは何も実行せず、プレビューと confirmToken を返します。そのトークンを付けて再度呼び出した場合にのみ処理が進みます。トークンはプレビューされたリクエストの内容に厳密に紐付けられています。引数を変更すると拒否され（DRAFT_CHANGED）、新しいプレビューが返されます。トークンを2回使うと、2回目の呼び出しは拒否されます（TOKEN_REUSED）。

変数	デフォルト
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で、書き込みツールがどのように動作するかを指定します。ask-user：2段階で実行されます。最初の呼び出しは何も実行せず、プレビューとトークンを返します。モデルはチャットでユーザーの承認を得てから、そのトークンを付けて再度呼び出す必要があります。auto：同じく2段階で実行されますが、モデルはプレビューを確認した後、自らトークンを使用できます。refuse：そのようなクライアントでは書き込みが拒否されます。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off でない限り、常に実際のプロンプトが表示されます。認識されない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off にすると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の動作が適用されます。プロンプトを表示できると申告しながら実際には表示しないクライアントで設定してください（書き込みが停止します — opencode 2.0.x）。それ以外の値は on として扱われ、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。サーバーの再起動後もトークンを有効にする必要がある場合にのみ設定してください。
MCP_HOST_CONFIRM_SECRET	未設定	mcp-host がこの登録用に設定します（データディレクトリがあります）。MCP_CONFIRM_SECRET が未設定で、かつ MCP_DATA_DIR が絶対パスの場合に使用されます。これにより、プレビューから確認済みの呼び出しまでの間にホストされた子プロセスがアイドル状態になって終了してもトークンが有効になり、使用済みトークンはデータディレクトリ内に記録されるため、再起動後に同じトークンが再受理されることはありません。

ツール

アカウントとセッション

ツール	備考
kia_session_status	設定済みか、初期設定済みか、書き込みモードはどれかを確認します。ネットワーク呼び出しは行わず、シークレットも返しません。メールアドレスは一部がマスクされ、デバイス ID は一部が省略されます。
kia_start_login	MFA 初期設定のステップ 1 です。拒否された場合に取り返しのつかない損失が生じるため、確認が必要です。
kia_send_otp	ステップ 2 です。SMS または EMAIL でパスコードを送信します。
kia_verify_otp	ステップ 3 です。パスコードを保存済みのセッションと交換します。シークレットは返しません。
kia_forget_session	保存済みのトークンを破棄し、初期設定をやり直せるようにします。ローカルのみで実行され、確認が必要です。

読み取り

ツール	備考
kia_list_vehicles	登録済みのすべての車両について、vehicleKey、ニックネーム、モデル、走行距離を表示します。VIN は末尾 6 文字のみ表示されます。
kia_vehicle_status	キャッシュされた状態を表示します。ドアロック、イグニッション（ign3 — EV では engine は false のままです）、ネストされた climate ブロックなどを確認できます。include_raw を指定すると、さらに情報が表示されます。高速ですが、最新度は最後のアップロード時点の状態に依存します。
kia_refresh_status	テレマティクスユニットを起動し、最新の情報を取得します。時間がかかり、少量の電力を消費しますが、それ自体はデータを返しません。実行後に kia_vehicle_status を読み取ってください。
kia_vehicle_location	最後に報告された位置と地図リンクを表示します。リアルタイムの GPS 測位ではありません。
kia_charge_targets	プラグの種類ごとの目標充電状態を表示します。

コマンド

ツール	モード	備考
kia_start_climate	comfort	事前空調です。温度はベストエフォートです。車両は、指定された温度ではなく、最後に設定した目標温度を報告する場合があります。
kia_stop_climate	comfort	climate.airCtrl を再読み込みして確認します。
kia_start_charge	comfort	検証済みです。車両を充電器に接続する必要があります。未接続の場合、Kia はリクエストを受け付けますが、何も起こりません。evStatus.batteryCharge で確認してください。
kia_stop_charge	comfort	検証済みです。evStatus.batteryCharge で確認してください。
kia_set_charge_limits	comfort	検証済みで、実行後に evc/gts と照合して再読み込みします。両方のプラグタイプを送信してください。リスト全体が保存済みの値に置き換わります。
kia_lock_doors	all	doorLock を再読み込みして確認します。
kia_unlock_doors	all	車両が物理的に無施錠の状態になります。ユーザーから明示的に依頼された場合にのみ実行してください。

ここに記載したすべてのエンドポイントは、2024 年式 EV9 で実機検証済みです。読み取りと 4 つのドア／空調コマンドは 2026-07-27 に、3 つの evc/* 充電コマンドは、車両を接続した状態で 2026-07-28 に検証しました。いずれも成功ステータスではなく、状態を再読み込みして動作を確認しています。Kia はコマンドを受け付けた時点で statusCode: 0 を返しますが、車両が動作するのはその数秒後です。また、車両が未接続の場合は成功を返すものの、何も起こりません。そのため、各コマンドの結果では「受け付け済み」と「確認済み」を別々に報告します。プロトコルの詳細な説明は docs/KIA-API.md をご覧ください。

開発

npm test              # unit tests (no network — fetch is mocked throughout)
npm run test:coverage # the same, with the enforced 100% thresholds
npm run build         # tsc + esbuild bundle

ライセンス

MIT