Hyundai Bluelink / Kia Connect

---

Home Assistant の Kia／Hyundai 統合の基盤となっているライブラリ、hyundai_kia_connect_api を使用しています。Hyundai と Kia はほとんどの地域で利用でき、Genesis は一部の地域で利用できます。詳しくは互換性をご覧ください。名称や設定では Bluelink（BLUELINK_*）を使っていますが、Kia Connect にも対応しています。Kia の場合は BLUELINK_BRAND=kia を設定してください。

「車は充電されていますか？ロックもされていますか？」 Santa Fe の充電量は 80％です（電気で約 52 km、燃料込みで合計 610 km の航続距離）。06:10 に充電が完了しました。すべてのドアがロックされ、窓も閉まっています。Bluelink が最後に車から情報を受信したのは 25 分前です。

「EV6 を 15 分間、暖めてください。」 完了しました。Kia から確認応答があったため、車内を 21 °C に設定して 15 分間暖めます。充電量は 64％なので、十分な残量があります。

メモ

これは非公式プロジェクトであり、Hyundai、Kia、Genesis とは無関係です。各社の API は非公開で、予告なく変更されます。

ツール

ツール	内容	必要な権限
list_vehicles	アカウントに登録されている車両
get_vehicle_status	バッテリー／燃料、航続距離、充電、空調、ロック、ドア、窓、タイヤ、警告、充電スケジュールに関する最終報告値。車両を起動しません。
refresh_vehicle_status	最新データを取得するために車両を起動します。呼び出し頻度に制限があります（下記参照）。
get_vehicle_location	緯度／経度、地図リンク、任意の住所	location
get_trips	1 日分の走行記録、または 1 か月分の概要
get_energy_usage	走行、空調、電子機器、バッテリー保護に関する日ごとのエネルギー使用量
get_command_status	以前に実行したコマンドの結果
lock_vehicle	ドアをロックします	writes
start_climate / stop_climate	車内を事前に調整します。温度、時間、デフロスター、リアウィンドウ／ミラーのヒーター、ステアリングヒーター、シートヒーターを設定できます	writes
start_charging / stop_charging	充電を開始または停止します	writes
set_charge_limits	AC／DC 充電の上限（EV 向け。ほとんどのプラグインハイブリッド車は非対応です）	writes
flash_hazard_lights	車を見つけるためにハザードランプを点滅させます	writes
unlock_vehicle	ドアのロックを解除します	writes + unlock

すべてのツールで vehicle（車名、VIN、または ID）を任意で指定できます。アカウントに車が 1 台だけ登録されている場合は、省略できます。

クイックスタート

アプリで利用できる Hyundai Bluelink または Kia Connect のアカウントと、uv または Docker が必要です。Claude Desktop ではどちらも必要ありません。以下をご覧ください。初期設定はヨーロッパの Hyundai 向けです。Kia の場合は BLUELINK_BRAND=kia を追加し、ヨーロッパ以外では BLUELINK_REGION を設定してください。

Claude Desktop 拡張機能

最新リリースから bluelink-mcp-<version>.mcpb をダウンロードして開くか、Claude Desktop の Settings → Extensions にドラッグします。ログイン情報、地域、ブランドを入力し、Claude に許可する操作を選択します。macOS、Windows、Linux で同じバンドルを使用できます。Claude Desktop が Python と依存関係をインストールします。Claude Desktopを参照してください。

uv を使った Claude Code（stdio）

git clone https://github.com/mattoddie/bluelink-mcp && cd bluelink-mcp
claude mcp add bluelink \
  -e [email protected] \
  -e BLUELINK_PASSWORD='your-password' \
  -e BLUELINK_PIN=1234 \
  -e BLUELINK_ALLOW_WRITES=true \
  -- uv run --directory "$PWD" bluelink-mcp

Kia の場合は、-e BLUELINK_BRAND=kia を追加します。他の stdio クライアントでも、同じ環境変数を使って同じコマンド（uv run --directory /path/to/bluelink-mcp bluelink-mcp）を実行します。

Docker（Streamable HTTP）

cp example.env .env   # fill in BLUELINK_* (BLUELINK_BRAND=kia for a Kia) and a random MCP_AUTH_TOKEN (openssl rand -hex 32)
docker compose up -d
claude mcp add --transport http bluelink http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

続けて「車の調子はどう？」と尋ねてください。

bluelink-mcp は io.github.mattoddie/bluelink-mcp としてMCP レジストリにも登録されています。そのため、レジストリを参照するクライアントは、Docker イメージ（stdio 経由）または Claude Desktop バンドルをそこからインストールできます。

設定

すべての設定は環境変数です。各設定の一覧と説明は example.env に記載されています。BLUELINK_PASSWORD、BLUELINK_PIN、MCP_AUTH_TOKEN は、それぞれ BLUELINK_PASSWORD_FILE、BLUELINK_PIN_FILE、MCP_AUTH_TOKEN_FILE で指定したファイルから読み込むこともできます。

変数	デフォルト
BLUELINK_USERNAME, BLUELINK_PASSWORD		Bluelink または Kia Connect アプリのログイン情報（必須）
BLUELINK_PIN		アプリの PIN。ヨーロッパではリモートコマンドに必要です。
BLUELINK_REGION	europe	europe、europe-cci、usa、canada、australia、nz、india、china、brazil
BLUELINK_BRAND	hyundai	hyundai（Bluelink）、kia（Kia Connect / UVO）、genesis（Genesis Connect）
BLUELINK_LANGUAGE	en	応答言語（ヨーロッパ）
BLUELINK_ALLOW_LOCATION	false	get_vehicle_location を登録
BLUELINK_LOCATION_PRECISION	4	返す緯度・経度の小数点以下の桁数（4 桁で約 10 m）
BLUELINK_GEOCODE	false	OpenStreetMap を使って位置情報に住所を追加（位置情報が必要）
BLUELINK_ALLOW_WRITES	false	コマンドツールを登録
BLUELINK_ALLOW_UNLOCK	false	unlock_vehicle も登録（書き込み操作が必要）
BLUELINK_AUDIT_LOG		各コマンドとライブ更新を JSON Lines 形式で記録：ファイルパス、または stderr
BLUELINK_MIN_REFRESH_MINUTES	10	車ごとの refresh_vehicle_status 呼び出し間の最短間隔
BLUELINK_MIN_COMMAND_SECONDS	60	同じ車に同じコマンドを再送するまでの最短間隔
BLUELINK_CACHE_SECONDS	60	ステータスの読み取り結果を再利用する時間
BLUELINK_LOGIN_RETRY_MINUTES	5	Bluelink にログインを拒否された後、再試行するまでの待機時間
BLUELINK_TOKEN_FILE	~/.local/state/bluelink-mcp/token.json（Docker では /data/token.json）	ログイントークンのキャッシュ。キャッシュを無効にするには空に設定します。
MCP_TRANSPORT	stdio（Docker では http）	stdio または http
LOG_LEVEL	info	debug、info、warning、error
MCP_HTTP_HOST, MCP_HTTP_PORT	127.0.0.1、8080	HTTP リッスンアドレス
MCP_AUTH_TOKEN		クライアントが送信する必要のあるベアラートークン（16 文字以上）。http では必須です。
MCP_ALLOWED_HOSTS		DNS リバインディング対策用の任意の Host ヘッダー許可リスト
MCP_ALLOWED_ORIGINS		MCP_ALLOWED_HOSTS が設定されている場合に、ブラウザベースのクライアントが使用できるオリジン

地域とブランドの選び方

英国およびヨーロッパのその他の地域では、まず従来の Bluelink と Kia Connect Europe サービスである europe をお試しください。一部の新しい Hyundai と Kia の車両では、代わりに CCI／「OneApp」バックエンドが使用されています。europe でログインまたはステータス取得に失敗する場合は、europe-cci をお試しください。

すべてのブランドをすべての地域で利用できるわけではありません。ニュージーランドでは Kia のみ、ブラジルでは Hyundai のみが利用でき、Genesis は europe-cci では動作しません。互換性テーブルを参照してください。

車（およびアカウント）に優しく

• 読み取りは車ではなく Bluelink から行います。 get_vehicle_status は、車が最後にアップロードした情報を返します。アップロードは、車の電源がオフになったとき、充電中、およびコマンドの実行後に行われます。last_updated_at を確認してください。
• 車を起動すると負担がかかります。 refresh_vehicle_status は車のモデムに通信させます。頻繁に実行すると 12V バッテリーが消耗し、Hyundai と Kia は欧州で 1 日あたりの API 呼び出し回数を制限しています。呼び出しは車ごとにレート制限されます（BLUELINK_MIN_REFRESH_MINUTES）。
• ログイン情報はキャッシュされます。 パスワードでのログインを繰り返すと、アカウントが一時的にブロックされることがあるため、サーバーはトークンを BLUELINK_TOKEN_FILE（モード 0600）に保存します。このファイルにはセッショントークンが含まれます（パスワードや PIN は含まれません）が、パスワードと同様に扱ってください。Bluelink にログインを拒否された後、サーバーはキャッシュを破棄し、再試行まで BLUELINK_LOGIN_RETRY_MINUTES 待機します。
• コマンドの実行には時間がかかります。 コマンドはモバイルネットワーク経由で送信され、通常 20～60 秒かかります。wait=true（デフォルト）の場合、ツールは車の確認を最大約 60 秒待ってから、後で確認できるよう action_id とともに pending を返します。その間もほかのツールは引き続き動作します。timeout は車から応答がなかったことを意味し、必ずしも何も起きなかったという意味ではありません。

安全性

BLUELINK_ALLOW_WRITES=true を設定しない限り、サーバーは読み取り専用です。また、unlock_vehicle には専用の BLUELINK_ALLOW_UNLOCK=true スイッチが必要です。ロック解除にはサーバー側での確認も必要です（ロック解除を参照）。各コマンドは車ごとにレート制限されます。ツールには MCP アノテーション（読み取り専用、破壊的）が付いているため、クライアントは実行前に確認できます。また、BLUELINK_AUDIT_LOG はすべてのコマンドを監査ログに記録します。HTTP モードでは、すべてのリクエストにベアラートークンが必要です。ポートの前段に TLS を設けず、インターネットに公開しないでください。

ドキュメント

はじめに	何もない状態から最初の質問をするまで
MCP クライアントの接続	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio
設定	すべての設定と、地域およびブランドの選択
bluelink-mcp の使用	質問例、キャッシュデータとライブデータ、コマンド
ツールリファレンス	すべてのツールと引数
セキュリティ · デプロイ · トラブルシューティング	適切な運用方法

開発

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

テストでは車両マネージャーのモックを使用するため、車のアカウントやネットワークは不要です。開発とコントリビューションガイドを参照してください。

ライセンス

MIT