home-assistant-mcp

Home Assistant Vibecode MCP

⚙️ この MCP サーバーは、Home Assistant のアドオンとしてインストールされる
Home Assistant Vibecode Agent と連携して動作します。
エージェントは Home Assistant インスタンス上で動作し、Cursor、VS Code、Claude Code などの AI IDE や、MCP に対応するほかの IDE に「目と手」を提供します。

必要なことを自然言語で説明するだけで、AI に Home Assistant のオートメーションを構築させたり、自分で作成したオートメーションの DevOps を任せたりできます。🏠🤖

目標を説明すると → AI が Home Assistant を調べ → カスタムソリューションを設計し → オンボードで自動的にデプロイします。🚀

オートメーションやスクリプトを自分で作りたい場合は、エージェントに DevOps と追加の作業者としての役割だけを任せることもできます。変更のすばやいアップロード、テストの実行、必要に応じたログ分析を行います。どこまで AI に任せ、どの程度深く関与させるかは、常にご自身で決められます。

スマートホームの管理方法を一新しましょう。このアドオンを使うと、Cursor、Visual Studio Code (VS Code)、またはMCP 対応 IDEから次の操作ができます。

• 📝 Home Assistant の設定、エンティティ、デバイスを分析する
• 🏗️ Home Assistant のヘルパーを含む、インテリジェントなオートメーション、スクリプト、システム一式を作成する。ヘルパーはプログラムから完全に管理できます
• 🎨 カード、レイアウト、スタイルを完全に制御しながら、Lovelace ダッシュボードを設計、カスタマイズする
• 🖌️ UI を自分好みにするテーマを作成、調整する
• 🔄 Git ベースの自動バージョン管理で変更を安全にデプロイする
• 🔍 ログ分析を通じて環境を監視、トラブルシューティングする
• 📦 HACS のインテグレーションとカスタムリポジトリをインストール、管理する

YAML を手動で編集したり、ドキュメントを探し回ったりする必要はもうありません。欲しいものを自然言語で説明するだけです！

例： 「ラジエーター用のスマートな温度制御をインストールして」 → AI があなたの TRV に合わせて最適化した、10 個以上のオートメーション、ヘルパー、センサー、スクリプトを作成します。

Model Context Protocol を基盤とし、HA Vibecode Agent を利用しています。

✨ 主な機能

🔍 環境を分析する

✅ エンティティ、オートメーション、スクリプト、ヘルパーなど、設定全体を読み取ります
✅ デバイスの機能、関連性、使用パターンを把握します
✅ 既存のロジックを学習し、現在のオートメーションやスクリプトの動作を分析します

---

🏗️ インテリジェントなシステムを構築する

✅ 相互に連携する複数のオートメーションを、数秒で構成してシステムを完成させます
✅ 実際の環境とニーズに合わせて、ヘルパーやセンサーを生成します
✅ 実際のエンティティ、エリア、デバイスに基づいて、最適化されたスクリプトを作成します
✅ 既存のロジックをゼロから作り直すのではなく、改善または統合してリファクタリングします

---

📊 ダッシュボードと UI

✅ Lovelace ダッシュボードをプログラムから作成、更新します
✅ 統計、グラフ、履歴、カスタムカードなどのカードを追加、削除、並べ替えます
✅ レイアウトとビューを制御し、部屋、エリア、シナリオを整理します
✅ 色、タイポグラフィ、スタイルを調整し、UI を自分好みにするテーマを設計します

---

🔒 安全な操作

✅ Git ベースのバージョン管理により、意味のあるコミットメッセージとともに変更をすべて記録します
✅ 人が読みやすいコミットを作成し、AI が「何を」「なぜ」変更したかを説明します
✅ 適用前に設定を検証し、問題が起きるリスクを軽減します
✅ ワンクリックでロールバックし、問題が発生した場合に以前の状態へ戻せます
✅ アクティビティログに、エージェントが行った操作とその時刻を完全に記録します

---

📦 コミュニティの機能を追加する

✅ HACS をインストールして設定する — 1000 以上のコミュニティインテグレーションを利用できます
✅ リポジトリを検索する — テーマ、プラグイン、カスタムコンポーネント、ダッシュボードを探せます
✅ インテグレーションをインストールする — 新しい HACS コンポーネントをワンコマンドでセットアップできます
✅ 最新の状態を保つ — すべての HACS リポジトリを一か所から更新できます

---

結果：
目標を伝える → AI が Home Assistant を調査する → カスタムソリューションを設計する → それを自動的に本体へデプロイする。🚀

---

🚀 他の Home Assistant 用 MCP モジュールとの違いは何ですか？

Cursor、VS Code、Claude 向けの MCP インテグレーションの多くは、ローカルマシン上でのみ動作し、SSH や場合によっては REST API 経由で Home Assistant と通信します。

Home Assistant を本格的に扱うには、それだけでは十分ではありません。

Home Assistant は、単なる YAML ファイルの集まりではありません。 複数の内部 API を公開しており、最も重要なものの一部は HA 内部から WebSocket API 経由でしか利用できません。

SSH 経由でのみ HA にアクセスする場合、AI は通常、リクエストのたびにヘルパースクリプトを生成してアップロードし、その後、ホスト上で動作を確認せずに実行する必要があります。 そのスクリプトは毎回異なる可能性があるため、各リクエストは少しブラックボックスのようになり、信頼性の高い自動化というより、ロシアンルーレットに近くなります。

このため、異なるアーキテクチャを選びました。

このプロジェクトは2 つのモジュールに分かれています：

Home Assistant Agent（このモジュール）— Home Assistant 内部でアドオンとして動作し、 関連するすべての API、ファイル、サービスにネイティブアクセスでき、 外部ツール向けに安全で明確に定義されたインターフェースを公開します。

Home Assistant MCP server — AI IDE（Cursor、VS Code など）と一緒にコンピューター上で動作し、 SSH の回避策ではなく、制御された API 経由で Agent と通信します（インストール手順は以下を参照）。

この設計により、Home Assistant をより迅速、安全、確実、かつ再現可能な形で操作できます。 AI IDE は、その動作が正しいことを期待しながら場当たり的なスクリプトを作り続けるのではなく、安定した API 経由で必要な操作とデータだけを取得できます。

---

📋 前提条件

インストールする前に、以下が必要です。

1. Home Assistant が動作していること（バージョンは問いません）
2. HA Vibecode Agent v2.2.0 以降がアドオンとしてインストールされていること
3. HA Vibecode Agent の Agent Key（初回起動時に自動生成されます）
4. AI 対応エディターがインストールされていること（Cursor、GitHub Copilot を導入した VS Code、Claude Code など）

---

🚀 クイックスタート（5 分）

ステップ 0：Node.js をインストールする（未インストールの場合）

MCP サーバーを実行するには、AI エディターがインストールされているコンピューターに Node.js が必要です。

1. Node.js がすでにインストールされているか確認します。ターミナルを開き、node --version を実行してください。
2. インストールされていない場合、またはバージョンが v20.0.0 未満の場合は、nodejs.org からダウンロードしてインストールしてください（可能であれば 24.x LTS ビルドを使用してください）。
3. インストール後、node --version で確認します。v20.0.0 以降が表示されるはずです（v24 LTS を推奨）。
4. 重要： Node.js は Home Assistant サーバーではなく、AI エディターを実行するコンピューターにインストールしてください。

ステップ 1：HA Vibecode Agent をインストールする

Home Assistant に Agent をインストールします：

1. 設定 → アドオン → アドオンストアに移動します。
2. ⋮ → リポジトリをクリックします。
3. 次を追加します：https://github.com/Coolver/home-assistant-vibecode-agent
4. HA Vibecode Agent（v2.0.0 以降）をインストールします。
5. Agent を起動します。

ステップ 2：AI エディターで MCP を設定する

Home Assistant から設定を取得します：

1. Home Assistant を開きます（通常は http://homeassistant.local:8123）
2. 設定 → アドオン → HA Vibecode Agent に移動します
3. 「Web UI を開く」 ボタンをクリックします
4. Cursor または VS Code のタブ（Home Assistant で使用する IDE に応じて）をクリックし、セットアップ手順に従います。MCP プロトコル経由で HA Agent に接続できるよう、Cursor または VS Code をインストールして設定する必要があります。
5. これで完了です。AI を使って Home Assistant のスクリプト、オートメーション、ダッシュボードを操作する準備ができました。 このプロジェクトが役に立ち、開発を支援したい場合は、ぜひ GitHub Star ⭐ を付けてください

ステップ 3：接続をテストする

すべてが正常に動作することを確認します：

AI エディター（Cursor、VS Code など）を開き、AI に次のメッセージを送信します：

Connect to my Home Assistant and show me:
1. List of all my climate entities
2. Current status of the HA Vibecode Agent

This will verify the MCP connection is working.

AI がエンティティとエージェントのステータスを正常に返したら、準備完了です！✅

トラブルシューティング： 接続に失敗した場合：

• HA Vibecode Agent が実行中であることを確認します
• AI エディターを完全に再起動したことを確認します
• 設定が正しく貼り付けられていることを確認します

ステップ 4：開発を始めましょう！

自然な言葉で作りたいものを説明するだけで、あとは AI が処理します！

---

🔧 設定

環境変数

変数	説明	必須	デフォルト
HA_AGENT_URL	HA Vibecode Agent の URL	はい	http://homeassistant.local:8099
HA_AGENT_KEY	認証用の Agent Key	はい	-

カスタムエージェント URL

エージェントが別の URL で実行されている場合：

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@coolver/home-assistant-mcp@latest"],
      "env": {
        "HA_AGENT_URL": "http://<home-assistant-host>:8099",
        "HA_AGENT_KEY": "your_api_key_here"
      }
    }
  }
}

---

🐛 トラブルシューティング

「Invalid Agent Key」エラー

1. mcp.json（HA_AGENT_KEY の項目）に入力した Agent Key が正しいことを確認します
2. 必要に応じてキーを再生成します：設定 → アドオン → HA Vibecode Agent → Web UI を開く
3. HA Vibecode Agent が実行中であることを確認します
4. エージェントにアクセスできることを確認します：curl http://homeassistant.local:8099/api/health

「Connection refused」

1. Home Assistant で HA Vibecode Agent が起動していることを確認します
2. HA_AGENT_URL の URL を確認します
3. ファイアウォールによってポート 8099 がブロックされていないことを確認します

「spawn npx ENOENT」エラー

このエラーは、Node.js がインストールされていないか、システムの PATH で見つからないことを意味します。

解決方法： Cursor を実行しているコンピューターに Node.js（v20.0.0 以上、v24 LTS を推奨）をインストールします：

1. https://nodejs.org から Node.js をダウンロードしてインストールします
2. インストール後、Cursor を完全に再起動します
3. ターミナルで node --version を実行し、インストールを確認します

重要： Node.js は Home Assistant サーバーではなく、Cursor、VS Code、Claude、その他の IDE を実行している お使いのコンピューター にインストールする必要があります。

---

🔐 セキュリティ

• ✅ すべての通信は HA Vibecode Agent（ポート 8099）を経由します
• ✅ MCP クライアントには Agent Key 認証を使用します
• ✅ エージェントはすべてのリクエストで Agent Key を検証します
• ✅ エージェントは Home Assistant API 操作に内部の SUPERVISOR_TOKEN を使用します
• ✅ Agent Key はローカル IDE の設定ファイルにのみ保存されます
• ⚠️ Agent Key を含む mcp.json を git にコミットしないでください！

---

🤝 関連プロジェクト

• HA Vibecode Agent - Home Assistant アドオン（必須）
• Model Context Protocol - プロトコル仕様

---

📝 ライセンス

MIT © Vladimir Eremeev

---

🔧 開発

プロジェクト構成

home-assistant-mcp/
├── package.json            # NPM package config
├── tsconfig.json           # TypeScript config
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── ha-client.ts       # HA Agent API client
│   ├── handlers.ts        # Tool request handlers
│   ├── tools.ts           # Legacy tool definitions
│   └── tools/             # Modular tool definitions
│       ├── index.ts       # Tool exports
│       ├── files.ts       # File operation tools
│       ├── system.ts      # System operation tools
│       └── dashboard.ts   # Dashboard tools
├── build/                 # Compiled JavaScript output
├── README.md
├── CHANGELOG.md
└── QUICK_START.md

アーキテクチャ

MCP サーバー（index.ts）← 通信プロトコル
↓
ツールハンドラー（handlers.ts）← ビジネスロジック
↓
HA クライアント（ha-client.ts）← HTTP API ラッパー
↓
HA Vibecode Agent（https://github.com/Coolver/home-assistant-vibecode-agent）（REST API）← Home Assistant との連携

🙏 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

---

💬 サポート

• 🐛 問題： GitHub Issues
• 💡 ディスカッション： GitHub Discussions

---

⭐ 応援する

このプロジェクトで AI を使ってスマートホームを操作できたら、⭐️を付けてください！