ホームアシスタント用モデルコンテキストプロトコルサーバー

サーバーは、MCP プロトコルを使用して、ローカル Home Assistant インスタンスへのアクセスを LLM アプリケーションと共有します。

Home Assistantインスタンスと言語学習モデル（LLM）間の強力なブリッジであり、モデルコンテキストプロトコル（MCP）を介してスマートホームデバイスの自然言語制御と監視を可能にします。このサーバーは、デバイス制御からシステム管理まで、Home Assistantエコシステム全体を管理するための包括的なAPIを提供します。

特徴

🎮デバイスコントロール：自然言語でHome Assistantデバイスをコントロール
🔄リアルタイム更新：サーバー送信イベント（SSE）を通じて即時更新を取得
🤖自動化管理：自動化を作成、更新、管理する
📊状態監視：デバイスの状態を追跡および照会する
🔐安全：トークンベースの認証とレート制限
📱モバイル対応: HTTP対応クライアントならどれでも動作します

SSEによるリアルタイム更新

サーバーには強力なServer-Sent Events（SSE）システムが搭載されており、Home Assistantインスタンスからのリアルタイム更新情報を提供します。これにより、以下のことが可能になります。

🔄あらゆるデバイスの状態変化を即座に把握
📡 自動化のトリガーと実行を監視する
🎯 特定のドメインまたはエンティティを購読する
📊 サービス呼び出しとスクリプト実行を追跡する

簡単な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がインストールされている
アドオン管理のためのスーパーバイザーアクセス

インストール

Smithery経由でインストール

Smithery経由で Claude Desktop 用の Home Assistant MCP Server を自動的にインストールするには:

npx -y @smithery/cli install @drejom/homeassistant-mcp --client claude

基本設定

# 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 build

Docker のセットアップ (推奨)

このプロジェクトには、さまざまなプラットフォーム間での容易な展開と一貫した環境を実現する Docker サポートが含まれています。

リポジトリをクローンします。
git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp
環境を構成する:
cp .env.example .env
Home 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=false
Docker 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インスタンスのURL
HASS_TOKEN : Home Assistant の長期アクセストークン
HASS_SOCKET_URL : Home Assistant の WebSocket URL
PORT : サーバーポート（デフォルト: 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 バージョン ( toSorted is not a function )
- 解決策: Node.js 20.10.0+ GXP39 にアップデートする
接続の問題
- Home Assistantが動作していることを確認する
- HASS_HOSTアクセス可能性を確認する
- トークンの権限を検証する
- リアルタイム更新のためにWebSocket接続を確保する
アドオン管理の問題
- スーパーバイザーのアクセスを確認する
- アドオンの互換性を確認する
- システムリソースを検証する
HACS統合の問題
- HACSのインストールを確認する
- HACS統合ステータスを確認する
- リポジトリアクセスを検証する
自動化の問題
- エンティティの可用性を確認する
- トリガー条件を確認する
- サービスコールの検証
- 実行ログを監視する

プロジェクトのステータス

✅完了

エンティティ、フロア、エリアへのアクセス
デバイス制御（ライト、空調、カバー、スイッチ、連絡先）
アドオン管理システム
HACSによるパッケージ管理
高度な自動化構成
基本的な状態管理
エラー処理と検証
Dockerコンテナ化
Jestテストのセットアップ
TypeScript統合
環境変数管理
ホームアシスタントAPI統合
プロジェクトドキュメント

🚧進行中

リアルタイム更新のためのWebSocket実装
強化されたセキュリティ機能
ツール構成の最適化
パフォーマンスの最適化
リソースコンテキストの統合
APIドキュメント生成
マルチプラットフォームデスクトップ統合
高度なエラー回復
カスタムプロンプトテスト
macOSとの統合強化
型安全性の改善
テスト範囲の拡大

貢献

リポジトリをフォークする
機能ブランチを作成する
変更を実装する
新しい機能のテストを追加する
すべてのテストに合格することを確認する
プルリクエストを送信する

リソース

ライセンス

MITライセンス - LICENSEファイルを参照

Integrations

ホームアシスタント用モデルコンテキストプロトコルサーバー

特徴

SSEによるリアルタイム更新

簡単なSSEの例

目次

主な特徴

コア機能 🎮

システム管理 🛠️

アーキテクチャの特徴 🏗️

前提条件

インストール

Smithery経由でインストール

基本設定

Docker のセットアップ (推奨)

Dockerの設定

Docker Compose 環境変数

構成

環境変数

設定ファイル

Claude Desktop（または他のクライアント）への追加

APIリファレンス

デバイス制御

共通エンティティコントロール

照明制御

アドオン管理

利用可能なアドオンの一覧

アドオンをインストール

アドオンの状態を管理する

パッケージ管理

HACS パッケージの一覧

パッケージのインストール

自動化管理

自動化を作成する

重複自動化

コア機能

状態管理

コンテキストの更新

アクションエンドポイント

アクションを実行

バッチアクション

クエリ関数

利用可能なアクションを取得する

コンテキストクエリ

WebSocketイベント

サポートされているイベント

エラー処理

レート制限

使用例

curlの使用

JavaScriptの使用

発達

トラブルシューティング

よくある問題

プロジェクトのステータス

貢献

リソース

ライセンス

Related Resources

Appeared in Searches