ha-nexus-agent

Home Assistant用MCPサーバー — 21ドメインにわたる202個のツールを通じて、AIアシスタントにスマートホームの完全な制御権を与えます。エンティティ（一括制御 + 音声アシスタントへの公開）、オートメーションとスクリプト（完全なCRUD + トレース）、ブループリント、ダッシュボード、ヘルパー、エリア、デバイスレジストリ、カレンダー、ToDoリスト、履歴、システム管理、YAML設定ファイル、Gitベースのバージョン管理、リアルタイムWebSocketイベント、エネルギーダッシュボード設定、ゾーン（ジオフェンシング）、ラベルとカテゴリ、あいまい検索と検出、Supervisor経由のアドオン管理、HACS統合などが含まれます。

Claude Code CLI、Claude Desktop、VS Code、Cursor、Windsurf、OpenAI Codex CLI、Gemini CLIで動作します。

インストール — Home Assistantアドオン（推奨）

1. Home Assistantで 設定 → アドオン → アドオンストア に移動します

2. 右上の3点メニュー（⋮）をクリックし、リポジトリ を選択します

3. 以下を追加します:

   https://github.com/Fistacho/ha-nexus-agent

4. Nexus Agent を見つけて インストール をクリックします

5. 開始 をクリックします

6. Web UIを開く をクリックします

Web UIにはAPIキーが表示され、各MCPクライアントに貼り付けるための設定が生成されます。手動でのトークン設定は不要で、アドオンが自動的にHome Assistantに接続します。

インストール — スタンドアロン（HA外部）

git clone https://github.com/Fistacho/ha-nexus-agent
cd ha-nexus-agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set HA_URL and HA_TOKEN
python server.py

http://localhost:7123 を開き、APIキーとMCPクライアント設定を取得します。

Home Assistantトークンの取得

1. HAで プロフィール → セキュリティ → 長期アクセス用トークン に移動します

2. トークンを作成 をクリックし、名前を nexus にします

3. .env ファイルの HA_TOKEN として貼り付けます

MCPクライアントの接続

Nexus起動後、http://your-ha-ip:7123 を開きます。セットアップページで各クライアント用の正確なコマンドや設定スニペットが生成されるので、コピーして貼り付けるだけです。

すべてのSSEベースのクライアントは以下に接続します:

http://your-ha-ip:7123/mcp?token=YOUR_API_KEY

Claude Code CLI

claude mcp add nexus --transport sse "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY" --scope user

OpenAI Codex CLI

codex mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

Gemini CLI

gemini mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

VS Code

.vscode/mcp.json を作成します:

{
  "servers": {
    "nexus": {
      "type": "sse",
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"
    }
  }
}

Cursor

~/.cursor/mcp.json に貼り付けます:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に貼り付けます:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Claude Desktop (スタンドアロン、サブプロセスモード)

%APPDATA%/Claude/claude_desktop_config.json (Windows) または ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) に貼り付けます:

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/ha-nexus-agent",
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_ha_token_here"
      }
    }
  }
}

ヒント: Nexus Web UI (http://your-ha-ip:7123) から、実際のパスとキーが含まれた正確な設定をコピーしてください。

機能

• 202個のMCPツール（21カテゴリ）

• リアルタイムWebSocket — 状態変化、イベント、トリガーをライブで購読

• Gitバージョン管理 — 設定変更を自動コミットし、即座にロールバック可能

• YAMLバリデーション — 設定ファイル書き込み前の検証

• セットアップWeb UI — 各クライアント用のMCP設定を自動生成

• HAアドオンネイティブ — アドオンストアからワンクリックインストール、手動トークン設定不要

• APIキー認証 — MCPエンドポイントを保護し、URLクエリパラメータでトークンを渡す

ツール概要

Gitバージョン管理

NexusはHA設定ディレクトリのGit履歴を保持します。リスクのある変更を行う前に git_safe_write_with_checkpoint を使用してください。現在の状態をコミットしてから変更を適用するため、問題が発生した場合は即座にロールバックできます。

git_init_config()                                    # run once
git_safe_write_with_checkpoint("automations.yaml", new_content)
git_rollback_file("automations.yaml")                # undo single file
git_rollback_to_commit("abc1234")                    # full rollback
git_log(limit=10)                                    # see history

環境変数