HomeAssistant-Light-MCP

Name: HomeAssistant-Light-MCP
Author: Koneisto

ローカル

github.com/Koneistoその他039 週間前に更新

リポジトリ

HomeAssistant-Light-MCP について

Home Assistantの照明操作とシーン管理を行うMCPサーバーです。MCPクライアントから照明を扱う用途向けで、安全上の設計としてスイッチやその他のエンティティは制御しません。

主な機能

01照明の状態・明るさ・色の確認
02電源・明るさ・色・エフェクトの調整
03シーンの作成・一覧・更新・削除
04シーンの有効化と照明の一括消灯
05シーンの診断と修復

活用シーン

01MCPクライアントから部屋の照明を調整
02照明シーンの保存と切り替え
03シーンの欠落確認と復元
04照明接続やシーンの問題調査

MCP 対応

ツールを通じて、Home Assistantの照明操作とシーン管理機能をMCPクライアントに公開します。stdioでローカル動作し、照明とシーンのみを扱います。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "koneisto-homeassistant-light": {
      "command": "npx",
      "args": [
        "-y",
        "ha-mcp-server"
      ],
      "env": {
        "HA_URL": "<HA_URL>",
        "HA_TOKEN": "<HA_TOKEN>"
      }
    }
  }
}

起動コマンドnpx -y ha-mcp-server

設定が必要な環境変数

HA_URLHome Assistant URL (e.g., http://192.168.1.100:8123)

HA_TOKENシークレットHome Assistant long-lived access token

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmha-mcp-server0.6.1stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
url	string	はい	Home Assistant の URL（例：'http://192.168.1.100:8123'）
token	string	はい	Home Assistant の長期アクセストークン

詳細

Home Assistant Light MCP

Home Assistant のライトを制御し、シーンを管理する Model Context Protocol（MCP）サーバーです。色の詳細な制御やシーン管理を提供し、公式の Home Assistant MCP を補完します。

このプロジェクトを気に入ったら、 GitHub で ⭐ を付けて、ほかの人にも広めてください！

設計方針：ライトのみ

この MCP が制御するのは、意図的にライトのみです。スイッチやその他のエンティティは制御しません。これは安全性を考慮した意図的な判断です。

スイッチは重要なシステムを制御する可能性があります — HVAC、ヒーター、エアコン、ウォーターポンプなど
誤作動は危険につながる可能性があります — 外出中にヒーターをつける、夏にエアコンを止めるなど
ライトは安全です — 最悪の場合でも、ライトが予期せず点灯または消灯するだけです

スイッチやその他のエンティティを制御する必要がある場合は、公式の Home Assistant MCP、または適切な安全対策を施したオートメーションを使用してください。

機能

ライトの表示 — すべてのライトの詳細を確認できます：
- 状態、明るさ、RGB カラー、色温度
- カラーモードと対応モード
- 使用可能なエフェクト（colorloop など）
- 色温度の範囲（最小／最大ケルビン）
ライトの調整 — ライトを制御できます（オン／オフ、明るさ、RGB カラー、色温度、エフェクト）
シーンの作成 — 現在の照明状態をシーンとして保存できます。モードは 2 種類です：
- exclusive — 有効にすると、ほかのライトを消灯します
- additive — シーンに含まれるライトだけに作用します
シーンの一覧表示 — 保存済みのシーンをすべて確認できます
シーンの有効化 — 保存済みのシーンを有効にします（IKEA Tradfri に対応）
シーンの更新 — 現在のライトの状態を使って、既存のシーンを更新します
シーンの削除 — シーンを削除します
一括消灯 — すべてのライトを消灯します（除外するライトを指定可能）

この MCP を使う理由

公式の Home Assistant MCP には制限があり、ライトの色を表示したり、状態の詳細情報を取得したりできません。この MCP はその不足を補います。

機能	公式 HA MCP	この MCP
ライトの色を表示	いいえ	はい
明るさを表示	限定的	詳細表示
カラーモードを表示	いいえ	はい
エフェクトを表示	いいえ	はい
RGB カラーを設定	いいえ	はい
色温度	いいえ	はい
エフェクトを設定	いいえ	はい
シーンを作成	いいえ	はい
IKEA Tradfri の修正	いいえ	はい

インストール

npm install -g ha-mcp-server

または、クローンしてビルドします：

git clone https://github.com/Koneisto/HomeAssistant-Light-MCP.git
cd HomeAssistant-Light-MCP
npm install
npm run build

設定

MCP クライアントの設定に追加します。

Claude Desktop

設定ファイルを編集します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

方法 1：npx を使用（推奨。グローバルインストール不要）

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "npx",
      "args": ["-y", "ha-mcp-server"],
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

方法 2：グローバルインストール

npm install -g ha-mcp-server

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "ha-mcp-server",
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

その他の MCP クライアント

同じ設定構造を、MCP 互換のクライアントであればどれでも使用できます。

Home Assistant トークンの取得

Home Assistant → Profile（左下）に移動します
「Long-Lived Access Tokens」までスクロールします
「Create Token」をクリックします
トークンをコピーします

使用例

ライトの表示

「すべてのライトを表示して」

「点灯しているライトはどれ？」

ライトの制御

「リビングのライトをつけて」

「寝室の明るさを 50% にして」

「キッチンのライトを赤にして」

「スタジオのライトを暖色系の白にして」

「廊下のライトで colorloop を開始して」

シーンの作成

「これを Movie Night として保存して」

シーンの有効化

「Movie Night を有効にして」

シーンの更新

「現在の設定で Evening Lights を更新して」

一括消灯

「すべてのライトを消して」

「バルコニー以外のライトをすべて消して」

ツールリファレンス

ツール	説明
`scene_show_lights`	状態、明るさ、色、エフェクト、カラーモードとともに、すべてのライトを表示します
`scene_adjust_light`	ライトを制御します（オン／オフ、明るさ、色、エフェクト）
`scene_create`	現在のライトの状態から新しいシーンを作成します
`scene_list`	すべてのシーンを一覧表示します
`scene_activate`	シーンを有効にします
`scene_update`	現在のライトを使って既存のシーンを更新します
`scene_delete`	シーンを削除します
`scene_blackout`	すべてのライトを消灯します（除外に対応）
`scene_diagnose`	ライトとシーンを診断し、接続状態を確認します
`scene_fix`	シーンの問題を修正し、バックアップから復元します
`scene_configure`	Home Assistant の URL とトークンを設定します

ライトのプロパティ

scene_show_lights は次の項目を返します。

state - オン／オフ
brightness / brightness_pct - 0～255 ／ 0～100%
rgb_color - [R, G, B] の値
color_temp_kelvin - 色温度
color_mode - 現在のモード（xy、color_temp、rgb、hs）
supported_color_modes - ライトが対応しているモード
effect - 有効なエフェクト（ある場合）
effect_list - 利用可能なエフェクト
color_temp_range - 最小／最大ケルビン値（対応している場合）

シーンモード

排他的：シーンに含まれないライトをすべて消灯します。部屋ごとのシーンに適しています。
追加的：シーンに含まれるライトだけに作用します。アクセント照明に適しています。

ローカルバックアップと複数インスタンスへの対応

この MCP は、作成したシーンのローカルバックアップを保持します。

自動バックアップ：シーンは ~/.config/ha-mcp-server/scenes-backup.json に保存されます
複数インスタンスを認識：別の MCP インスタンス（または HA の UI）がシーンを変更したことを検出します
スマートな競合解決：複数のソースからの変更を統合します
復元機能：Home Assistant からシーンが失われた場合に復元できます

診断（`scene_diagnose`）

ライトとシーンを分析して、問題を特定します。

ライトの接続状態と応答時間をテストします
接続タイプ（Zigbee、WiFi、Bluetooth）を検出します
null 値やライトの欠落があるシーンを検出します
Home Assistant の状態とローカルバックアップを比較します
排他的シーンにまだ追加されていない新しいライトを報告します

例：「ライトの診断を実行して」

修正と修復（`scene_fix`）

シーンの問題を修復するための4つのアクションがあります。

アクション	説明
`fix_all`	すべてのシーンを自動修正します。null 値を削除し、排他的シーンに不足しているライトを追加します
`fix_scene`	名前を指定して特定のシーンを修正します
`test_scene`	シーンを有効にして、問題の内容を報告します
`restore_from_backup`	Home Assistant からシーンが失われた場合、ローカルバックアップから復元します

例：「すべてのシーンを修正して」、または 「バックアップから Evening Lights を復元して」

IKEA Tradfri への対応

IKEA Tradfri のライトでは、RGB カラーモードと色温度（ケルビン）モードを切り替える際に既知の問題があります。電球が明るさや色の値を受け付ける前に、モード変更の処理に時間が必要です。

注： Home Assistant のネイティブシーンは、このタイミングの問題により Tradfri のライトでは安定して動作しません。この MCP は、適切な遅延を設けてシーンを個別に管理することで回避策を提供します。

この MCP は Tradfri のライトを自動的に処理します。

メーカー名から Tradfri デバイスを検出します
モード切り替えと後続のコマンドの間に500ミリ秒の遅延を追加します
明るさの調整と色／温度の変更を適切な順序で実行します

これらの修正がない場合、Tradfri のライトはモード切り替え時にコマンドを無視したり、色が正しくならなかったりすることがよくあります。

セキュリティ

データはローカルにとどまります

すべての通信は、お使いのコンピューターと Home Assistant インスタンスの間で直接行われます
外部サーバーや第三者にデータが送信されることはありません
MCP サーバーは stdio 経由でお使いのマシン上でローカルに実行されます（ネットワークポートは開きません）

トラッキングなし

あなたを追跡するほどの関心はありません

トークンの安全性

Home Assistant のトークンは、お使いのローカルマシンにのみ保存されます
ファイルにトークンを保存しないよう、環境変数を使用してください
トークンはご自身の Home Assistant インスタンスにのみ送信されます
Home Assistant の設定から、いつでもトークンを取り消せます

このサーバーがアクセスできる対象

ご自身の Home Assistant 内のライトとシーンのみです
Home Assistant のその他のエンティティ（センサー、ロック、カメラなど）にはアクセスできません
ライトの制御とシーンの管理以外の変更はできません

コントリビューション

バグを見つけた場合やアイデアがある場合は、イシューを作成するか、プルリクエストを送信してください！

ライセンス

MIT — 自由にご利用ください。クレジット表記は歓迎しますが、必須ではありません。

作者

Koneisto

優先順位に少々疑問のある人々によって作られました

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。