ホームアシスタント用モデルコンテキストプロトコルサーバー
サーバーは、MCP プロトコルを使用して、ローカル Home Assistant インスタンスへのアクセスを LLM アプリケーションと共有します。
Home Assistantインスタンスと言語学習モデル(LLM)間の強力なブリッジであり、モデルコンテキストプロトコル(MCP)を介してスマートホームデバイスの自然言語制御と監視を可能にします。このサーバーは、デバイス制御からシステム管理まで、Home Assistantエコシステム全体を管理するための包括的なAPIを提供します。
特徴
🎮デバイスコントロール:自然言語でHome Assistantデバイスをコントロール
🔄リアルタイム更新:サーバー送信イベント(SSE)を通じて即時更新を取得
🤖自動化管理:自動化を作成、更新、管理する
📊状態監視:デバイスの状態を追跡および照会する
🔐安全:トークンベースの認証とレート制限
📱モバイル対応: HTTP対応クライアントならどれでも動作します
Related MCP server: Home Assistant MCP
SSEによるリアルタイム更新
サーバーには、Home Assistantインスタンスからのリアルタイム更新を提供する強力なServer-Sent Events(SSE)システムが搭載されています。これにより、以下のことが可能になります。
🔄あらゆるデバイスの状態変化を即座に把握
📡 自動化のトリガーと実行を監視する
🎯 特定のドメインまたはエンティティを購読する
📊 サービス呼び出しとスクリプト実行を追跡する
簡単なSSEの例
const eventSource = new EventSource(
'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Update received:', data);
};SSE システムの完全なドキュメントについては、 SSE_API.md を参照してください。
目次
主な特徴
コア機能 🎮
スマートデバイスコントロール
💡ライト:明るさ、色温度、RGBカラー
🌡️気候: 温度、HVAC モード、ファン モード、湿度
🚪カバー:位置と傾きのコントロール
🔌スイッチ:オン/オフ制御
🚨センサーと接点:状態監視
🎵メディアプレーヤー:再生コントロール、音量、ソース選択
🌪️ファン:速度、振動、方向
🔒ロック:ロック/ロック解除の制御
🧹掃除機:スタート、停止、ベースに戻る
📹カメラ:動き検知、スナップショット
システム管理 🛠️
アドオン管理
利用可能なアドオンを参照する
アドオンのインストール/アンインストール
アドオンの起動/停止/再起動
バージョン管理
構成アクセス
パッケージ管理(HACS)
Home Assistantコミュニティストアとの統合
複数のパッケージ タイプをサポート:
カスタム統合
フロントエンドテーマ
Pythonスクリプト
AppDaemonアプリ
NetDaemonアプリ
バージョン管理と更新
リポジトリ管理
自動化管理
自動化の作成と編集
高度な構成オプション:
複数のトリガータイプ
複雑な条件
アクションシーケンス
実行モード
既存の自動化を複製および変更する
自動化ルールを有効/無効にする
自動化を手動でトリガーする
アーキテクチャの特徴 🏗️
インテリジェントな組織
エリアとフロアベースのデバイスグループ化
状態の監視とクエリ
スマートなコンテキスト認識
履歴データへのアクセス
堅牢なアーキテクチャ
包括的なエラー処理
州の検証
安全なAPI統合
TypeScriptの型安全性
広範なテスト範囲
前提条件
Node.js 20.10.0 以上
NPMパッケージマネージャー
コンテナ化のためのDocker Compose
Home Assistantインスタンスの実行
Home Assistant 長期アクセス トークン (トークンの取得方法)
パッケージ管理機能のためにHACSがインストールされている
アドオン管理のためのスーパーバイザーアクセス
インストール
基本設定
# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
# Install dependencies
npm install
# Build the project
npm run buildDocker のセットアップ (推奨)
このプロジェクトには、さまざまなプラットフォーム間での容易な展開と一貫した環境を実現する Docker サポートが含まれています。
リポジトリをクローンします。
git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp環境を構成する:
cp .env.example .envHome Assistant の設定に合わせて
.envファイルを編集します。# Home Assistant Configuration HASS_HOST=http://homeassistant.local:8123 HASS_TOKEN=your_home_assistant_token HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # Server Configuration PORT=3000 NODE_ENV=production DEBUG=falseDocker Compose でビルドして実行します。
# Build and start the containers docker compose up -d # View logs docker compose logs -f # Stop the service docker compose down**インストールの確認:**サーバーは
http://localhost:3000で稼働しているはずです。ヘルスエンドポイントはhttp://localhost:3000/healthで確認できます。アプリケーションを更新します。
# Pull the latest changes git pull # Rebuild and restart the containers docker compose up -d --build
Dockerの設定
Docker セットアップには以下が含まれます。
最適な画像サイズのための多段階ビルド
コンテナ監視のヘルスチェック
環境設定のためのボリュームマウント
障害発生時のコンテナの自動再起動
APIアクセス用にポート3000を公開
Docker Compose 環境変数
すべての環境変数は.envファイルで設定できます。以下の変数がサポートされています。
HASS_HOST: Home AssistantインスタンスのURLHASS_TOKEN: Home Assistant の長期アクセストークンHASS_SOCKET_URL: Home Assistant の WebSocket URLPORT: サーバーポート(デフォルト: 3000)NODE_ENV: 環境(本番/開発)DEBUG: デバッグモードを有効にする (true/false)
構成
環境変数
# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123 # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # WebSocket URL
# Server Configuration
PORT=3000 # Server port (default: 3000)
NODE_ENV=production # Environment (production/development)
DEBUG=false # Enable debug mode
# Test Configuration
TEST_HASS_HOST=http://localhost:8123 # Test instance URL
TEST_HASS_TOKEN=test_token # Test token設定ファイル
開発:
.env.exampleを.env.developmentにコピーします。本番環境:
.env.exampleを.env.productionにコピーするテスト:
.env.exampleを.env.testにコピーする
Claude Desktop(または他のクライアント)への追加
新しいHome Assistant MCPサーバーを使用するには、Claude Desktopをクライアントとして追加します。以下の設定を追加してください。これはClaude内でMCPを実行するため、Dockerメソッドでは動作しませんのでご注意ください。
{
"homeassistant": {
"command": "node",
"args": [<path/to/your/dist/folder>]
"env": {
NODE_ENV=development
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
PORT=3000
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
LOG_LEVEL=debug
}
}
}
APIリファレンス
デバイス制御
共通エンティティコントロール
{
"tool": "control",
"command": "turn_on", // or "turn_off", "toggle"
"entity_id": "light.living_room"
}照明制御
{
"tool": "control",
"command": "turn_on",
"entity_id": "light.living_room",
"brightness": 128,
"color_temp": 4000,
"rgb_color": [255, 0, 0]
}アドオン管理
利用可能なアドオンの一覧
{
"tool": "addon",
"action": "list"
}アドオンをインストール
{
"tool": "addon",
"action": "install",
"slug": "core_configurator",
"version": "5.6.0"
}アドオンの状態を管理する
{
"tool": "addon",
"action": "start", // or "stop", "restart"
"slug": "core_configurator"
}パッケージ管理
HACSパッケージの一覧
{
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}パッケージのインストール
{
"tool": "package",
"action": "install",
"category": "integration",
"repository": "hacs/integration",
"version": "1.32.0"
}自動化管理
自動化を作成する
{
"tool": "automation_config",
"action": "create",
"config": {
"alias": "Motion Light",
"description": "Turn on light when motion detected",
"mode": "single",
"trigger": [
{
"platform": "state",
"entity_id": "binary_sensor.motion",
"to": "on"
}
],
"action": [
{
"service": "light.turn_on",
"target": {
"entity_id": "light.living_room"
}
}
]
}
}重複自動化
{
"tool": "automation_config",
"action": "duplicate",
"automation_id": "automation.motion_light"
}コア機能
状態管理
GET /api/state
POST /api/stateシステムの現在の状態を管理します。
リクエスト例:
POST /api/state
{
"context": "living_room",
"state": {
"lights": "on",
"temperature": 22
}
}コンテキストの更新
POST /api/context現在のコンテキストを新しい情報で更新します。
リクエスト例:
POST /api/context
{
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}アクションエンドポイント
アクションを実行
POST /api/action指定されたパラメータを使用して指定されたアクションを実行します。
リクエスト例:
POST /api/action
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}バッチアクション
POST /api/actions/batch複数のアクションを順番に実行します。
リクエスト例:
POST /api/actions/batch
{
"actions": [
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room"
}
},
{
"action": "set_temperature",
"parameters": {
"temperature": 22
}
}
]
}クエリ関数
利用可能なアクションを取得する
GET /api/actions利用可能なすべてのアクションのリストを返します。
応答例:
{
"actions": [
{
"name": "turn_on_lights",
"parameters": ["room", "brightness"],
"description": "Turns on lights in specified room"
},
{
"name": "set_temperature",
"parameters": ["temperature"],
"description": "Sets temperature in current context"
}
]
}コンテキストクエリ
GET /api/context?type=currentコンテキスト情報を取得します。
応答例:
{
"current_context": {
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
}WebSocketイベント
サーバーは、WebSocket 接続を介したリアルタイム更新をサポートします。
// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
};サポートされているイベント
state_change: システムの状態が変化したときに発行されますcontext_update: コンテキストが更新されたときに発行されますaction_executed: アクションが完了したときに発行されますerror: エラーが発生したときに発行されます
イベントデータの例:
{
"event": "state_change",
"data": {
"previous_state": {
"lights": "off"
},
"current_state": {
"lights": "on"
},
"timestamp": "2024-03-20T10:30:00Z"
}
}エラー処理
すべてのエンドポイントは標準の HTTP ステータス コードを返します。
200: 成功
400: 不正なリクエスト
401: 権限がありません
403: 禁止
404: 見つかりません
500: 内部サーバーエラー
エラー応答形式:
{
"error": {
"code": "INVALID_PARAMETERS",
"message": "Missing required parameter: room",
"details": {
"missing_fields": ["room"]
}
}
}レート制限
API は不正使用を防ぐためにレート制限を実装しています。
通常のエンドポイントの場合、IPごとに1分あたり100リクエスト
WebSocket 接続の場合、IP ごとに 1 分あたり 1000 件のリクエスト
レート制限を超えると、サーバーは次を返します:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"reset_time": "2024-03-20T10:31:00Z"
}
}使用例
curlの使用
# Get current state
curl -X GET \
http://localhost:3000/api/state \
-H 'Authorization: ApiKey your_api_key_here'
# Execute action
curl -X POST \
http://localhost:3000/api/action \
-H 'Authorization: ApiKey your_api_key_here' \
-H 'Content-Type: application/json' \
-d '{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}'JavaScriptの使用
// Execute action
async function executeAction() {
const response = await fetch('http://localhost:3000/api/action', {
method: 'POST',
headers: {
'Authorization': 'ApiKey your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
action: 'turn_on_lights',
parameters: {
room: 'living_room',
brightness: 80
}
})
});
const data = await response.json();
console.log('Action result:', data);
}発達
# Development mode with hot reload
npm run dev
# Build project
npm run build
# Production mode
npm run start
# Run tests
npx jest --config=jest.config.cjs
# Run tests with coverage
npx jest --coverage
# Lint code
npm run lint
# Format code
npm run formatトラブルシューティング
よくある問題
Node.js バージョン (
解決策: Node.js 20.10.0+ GXP38 にアップデートする
接続の問題
Home Assistantが動作していることを確認する
HASS_HOSTアクセス可能性を確認するトークンの権限を検証する
リアルタイム更新のためにWebSocket接続を確保する
アドオン管理の問題
スーパーバイザーのアクセスを確認する
アドオンの互換性を確認する
システムリソースを検証する
HACS統合の問題
HACSのインストールを確認する
HACS統合ステータスを確認する
リポジトリアクセスを検証する
自動化の問題
エンティティの可用性を確認する
トリガー条件を確認する
サービスコールの検証
実行ログを監視する
プロジェクトのステータス
✅完了
エンティティ、フロア、エリアへのアクセス
デバイス制御(ライト、空調、カバー、スイッチ、連絡先)
アドオン管理システム
HACSによるパッケージ管理
高度な自動化構成
基本的な状態管理
エラー処理と検証
Dockerコンテナ化
Jestテストのセットアップ
TypeScript統合
環境変数管理
ホームアシスタントAPI統合
プロジェクトドキュメント
🚧進行中
リアルタイム更新のためのWebSocket実装
強化されたセキュリティ機能
ツール構成の最適化
パフォーマンスの最適化
リソースコンテキストの統合
APIドキュメント生成
マルチプラットフォームデスクトップ統合
高度なエラー回復
カスタムプロンプトテスト
macOSとの統合強化
型安全性の改善
テスト範囲の拡大
貢献
リポジトリをフォークする
機能ブランチを作成する
変更を実装する
新しい機能のテストを追加する
すべてのテストに合格することを確認する
プルリクエストを送信する
リソース
ライセンス
MITライセンス - LICENSEファイルを参照
Appeared in Searches
- A server for controlling smart home lights
- An MCP for managing lifestyle, coordinating daily routines, exercise, and study tasks
- Searching for information about license types or information starting with 'f'
- A server for finding information about guitars
- Software or solutions for managing a fleet of computers