Home Assistant Integration

🚀 家庭助手 MCP

このモデルコンテキストプロトコル（MCP）は、人工知能アシスタントを通じて家庭用アシスタントデバイスを制御するためのものです。人工知能アシスタントが家庭用アシスタントデバイスを制御することを可能にし、家庭内のデバイス制御をよりスマートにします。

🚀 クイックスタート

このMCPを使用することで、人工知能アシスタントが家庭用アシスタントデバイスを制御できるようになります。以下のような機能を提供します。

1. 家庭用アシスタントインスタンス内でエンティティを検索します。
2. デバイスのオン/オフを制御します。
3. ライトの色と明るさを制御します。

✨ 主な機能

• 家庭用アシスタントデバイスの制御：人工知能アシスタントを通じて、家庭内のデバイスを簡単に制御できます。
• エンティティ検索：家庭用アシスタントインスタンス内でエンティティを検索できます。
• ライト制御：ライトの色と明るさを細かく制御できます。

📦 インストール

前提条件

• Python 3.11以上のバージョン
• APIを通じてアクセス可能な稼働中の家庭用アシスタントインスタンス
• 家庭用アシスタントの長期アクセストークン

インストール手順

1. このリポジトリをクローンします。
2. Python環境を設定します。

cd home-assistant
python -m venv .venv
source .venv/bin/activate  # Windowsの場合は：.venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .

📚 ドキュメント

設定

家庭用アシスタントの長期アクセストークンの取得

1. 家庭用アシスタントインスタンスにアクセスします。
2. 設定ファイルに移動します（サイドバーのユーザー名をクリック）。
3. ページの下部の「長期アクセストークン」までスクロールします。
4. 「MCP 統合」などの説明付きの新しいトークンを作成します。
5. トークンをコピーします（作成時にのみ表示されます）。

Cursor AIでの設定

以下の設定をMCP設定に追加します。

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

以下を置き換えます。

• /path/to/your/home-assistant を実際の家庭用アシスタントディレクトリのパスに置き換えます。
• your_home_assistant_token_here を長期の家庭用アシスタントアクセストークンに置き換えます。

家庭用アシスタントURLの設定

デフォルトでは、MCPは http://homeassistant.local:8123 にある家庭用アシスタントに接続しようとします。 もし家庭用アシスタントが別のURLにある場合は、app/config.py の HA_URL 変数を変更できます。

💻 使用例

基本的な使用法

設定が完了したら、Cursor AIを使用して家庭用アシスタントデバイスを制御できます。

• デバイスの検索：例えば、「リビングルームのライトを探す」
• デバイスの制御：例えば、「キッチンのライトをオンにする」
• ライトの色の制御：例えば、「リビングルームのライトを赤色に設定する」
• 明るさの調整：例えば、「ダイニングルームのライトを青色に、50%の明るさに設定する」

高度な使用法

MCPは現在、高度なライト制御機能をサポートしています。

色の制御

互換性のあるライトの任意のRGB色を設定できます。

• RGB値（各コンポーネントは0 - 255）を使用して色を指定します。
• 例：set_device_color("light.living_room", 255, 0, 0) で赤色に設定します。

明るさの制御

ライトの明るさを調整できます。

• オプションの明るさパラメータ（0 - 255）を指定できます。
• 色の変更と組み合わせて使用できます。
• 例：set_device_color("light.dining_room", 0, 0, 255, brightness=128) で中程度の明るさの青色に設定します。

🔧 技術詳細

トラブルシューティング

• 認証エラーが発生した場合は、トークンが正しく、期限切れになっていないことを確認してください。
• 家庭用アシスタントインスタンスが設定されたURLにアクセスできることを確認してください。
• 色の制御に問題がある場合は：
  • ライトエンティティがRGB色制御をサポートしていることを確認してください。
  • 色を変更する前にライトがオンになっていることを確認してください。

将来的な機能

動的エンティティ公開

現在の実装では、自然言語でエンティティを検索し、その後デバイスを制御する2段階のプロセスが必要です。

1. 自然言語でエンティティを検索します。
2. 特定の entity_id を使用してエンティティを制御します。

計画されている機能強化は、エンティティをMCPにより動的に公開する方法を作成し、直接制御できるようにすることです。 例えば：

• ライトの場合：「リビングルームのライト」
• スマートコンセントの場合：「キッチンのコンセント」

これにより、MCPはIDを検索することなく直接デバイスとやり取りできるようになります。