Homeassistant Light MCP

🚀 Home Assistant Light MCP

Home Assistantの照明を制御し、シーンを管理するためのモデルコンテキストプロトコル（MCP）サーバーです。公式のHome Assistant MCPを補完し、色付きの詳細な照明制御とシーン管理を提供します。

このプロジェクトが気に入ったら？ GitHubで⭐を付けて、他の人にも発見してもらいましょう！

🚀 クイックスタート

設計哲学：照明のみ

このMCPは意図的に照明のみを制御します。スイッチや他のエンティティは制御しません。これは安全上の配慮からの決定です。

• スイッチは重要なシステムを制御する可能性があります - HVAC、ヒーター、エアコン、水ポンプなど。
• 誤ってアクティブ化すると危険な場合があります - 外出中にヒーターがオンになったり、夏にエアコンが停止したりすることがあります。
• 照明は安全です - 最悪の場合でも、照明が予期せずオンまたはオフになるだけです。

スイッチや他のエンティティを制御する必要がある場合は、公式のHome Assistant MCPまたは適切な安全策を備えた自動化を使用してください。

✨ 主な機能

• 照明の表示 - すべての照明を詳細情報とともに表示します。
  • 状態、明るさ、RGB色、色温度
  • 色モードとサポートされているモード
  • 利用可能なエフェクト（カラーループなど）
  • 色温度範囲（最小/最大ケルビン）
• 照明の調整 - 照明を制御します（オン/オフ、明るさ、RGB色、色温度、エフェクト）。
• シーンの作成 - 現在の照明設定をシーンとして保存します。2つのモードがあります。
  • exclusive - アクティブ化時に他の照明をオフにします。
  • additive - シーン内の照明のみに影響を与えます。
• シーンの一覧表示 - 保存されたすべてのシーンを表示します。
• シーンのアクティブ化 - 保存されたシーンをアクティブ化します（IKEA Tradfri対応）。
• シーンの更新 - 現在の照明状態で既存のシーンを更新します。
• シーンの削除 - シーンを削除します。
• 全消灯 - すべての照明をオフにします（オプションで除外する照明を指定できます）。

なぜこのMCPが必要なのか？

公式のHome Assistant MCPには制限があり、照明の色を表示したり、詳細な状態情報を提供したりできません。このMCPはそのギャップを埋めます。

📦 インストール

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トークンの取得方法

1. Home Assistantにアクセスし、左下の「プロフィール」をクリックします。
2. 「長期アクセストークン」までスクロールします。
3. 「トークンを作成」をクリックします。
4. トークンをコピーします。

💻 使用例

照明の表示

"すべての照明を表示して"

"どの照明がオンになっていますか？"

照明の制御

"リビングルームの照明をオンにして"

"寝室の照明を50%の明るさに設定して"

"キッチンの照明を赤色にして"

"スタジオの照明を暖かい白色に設定して"

"ホールの照明でカラーループを開始して"

シーンの作成

"これを映画の夜として保存して"

シーンのアクティブ化

"映画の夜をアクティブにして"

シーンの更新

"夕方の照明を現在の設定で更新して"

全消灯

"すべての照明をオフにして"

"バルコニーの照明を除いて、すべての照明をオフにして"

📚 ドキュメント

ツールリファレンス

照明のプロパティ

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 - 最小/最大ケルビン（サポートされている場合）

シーンモード

• 排他的（Exclusive）: シーンに含まれないすべての照明をオフにします。部屋固有のシーンに適しています。
• 追加的（Additive）: シーン内の照明のみに影響を与えます。アクセント照明に適しています。

ローカルバックアップとマルチインスタンスサポート

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

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

診断 (scene_diagnose)

照明とシーンを分析して問題を特定します。

• 照明の接続性と応答時間をテストします。
• 接続タイプ（Zigbee、WiFi、Bluetooth）を検出します。
• ヌル値または欠落している照明を持つシーンを見つけます。
• Home Assistantの状態とローカルバックアップを比較します。
• 排他的シーンにまだ含まれていない新しい照明を報告します。

例: "照明の診断を実行して"

修正と修復 (scene_fix)

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

例: "すべてのシーンを修正して" または "夕方の照明をバックアップから復元して"

IKEA Tradfriサポート

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

注意: Home Assistantのネイティブシーンは、これらのタイミング問題のため、Tradfriの照明では安定して動作しません。このMCPは、適切な遅延を持ってシーンを独立して管理することで解決策を提供します。

このMCPは、以下の方法でTradfriの照明を自動的に処理します。

• メーカー名でTradfriデバイスを検出します。
• モード切り替えとその後のコマンドの間に500msの遅延を追加します。
• 色/温度の変更と明るさの調整を適切にシーケンス化します。

これらの修正がない場合、Tradfriの照明はモードを切り替えるときにコマンドを無視したり、間違った色を表示したりすることがよくあります。

セキュリティ

データはローカルに保存されます

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

トラッキングは行われません

• あなたをトラッキングすることはありません。

トークンの安全性

• あなたのHome Assistantトークンは、あなたのローカルマシンにのみ保存されます。
• トークンをファイルに保存する代わりに、環境変数を使用してください。
• トークンはあなた自身のHome Assistantインスタンスにのみ送信されます。
• Home Assistantの設定からいつでもトークンを取り消すことができます。

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

• Home Assistant内の照明とシーンのみにアクセスできます。
• 他のHome Assistantエンティティ（センサー、ロック、カメラなど）にはアクセスできません。
• 照明制御とシーン管理以外の変更を行うことはできません。

コントリビュート

バグを見つけたり、アイデアがある場合は、問題を開く またはプルリクエストを送信してください！

📄 ライセンス

MITライセンスです。自由に使用できます。帰属表示は推奨されますが、必須ではありません。

作者

Koneisto

優先順位が怪しい人々によって構築されました