Model Context Protocol Server for Home Assistant

Home Assistant 用 Model Context Protocol サーバー

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

Home Assistant インスタンスと大規模言語モデル（LLM）をつなぐ強力なブリッジです。Model Context Protocol（MCP）を通じて、スマートホームデバイスを自然言語で制御・監視できます。このサーバーは、デバイスの制御からシステム管理まで、Home Assistant エコシステム全体を管理するための包括的な API を提供します。

特長

• 🎮 デバイス制御：自然言語で Home Assistant のあらゆるデバイスを制御します
• 🔄 リアルタイム更新：Server-Sent Events（SSE）で即時更新を取得します
• 🤖 自動化管理：自動化を作成、更新、管理します
• 📊 状態監視：デバイスの状態を追跡、照会します
• 🔐 セキュア：トークンベース認証とレート制限に対応します
• 📱 モバイル対応：HTTP 対応のあらゆるクライアントで動作します

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 をご覧ください。

目次

• 主な特長
• 前提条件
• インストール
  • 基本的なセットアップ
  • Docker のセットアップ（推奨）
• 設定
• 開発
• API リファレンス
  • デバイス制御
  • アドオン管理
  • パッケージ管理
  • 自動化管理
• 自然言語連携
• トラブルシューティング
• プロジェクトの状況
• コントリビューション
• リソース
• ライセンス

主な特長

主な機能 🎮

• スマートデバイス制御
  • 💡 ライト：明るさ、色温度、RGB カラー
  • 🌡️ 空調：温度、HVAC モード、ファンモード、湿度
  • 🚪 カバー：位置と傾きの制御
  • 🔌 スイッチ：オン／オフ制御
  • 🚨 センサーと接点：状態監視
  • 🎵 メディアプレーヤー：再生制御、音量、ソース選択
  • 🌪️ ファン：速度、首振り、方向
  • 🔒 ロック：施錠／解錠制御
  • 🧹 掃除機：開始、停止、ドックへの帰還
  • 📹 カメラ：動体検知、スナップショット

システム管理 🛠️

• アドオン管理

  • 利用可能なアドオンを表示
  • アドオンをインストール／アンインストール
  • アドオンを起動／停止／再起動
  • バージョン管理
  • 設定へのアクセス

• パッケージ管理（HACS）

  • Home Assistant Community Store との連携
  • 複数のパッケージタイプに対応：
    • カスタムインテグレーション
    • フロントエンドテーマ
    • Python スクリプト
    • AppDaemon アプリ
    • NetDaemon アプリ
  • バージョン管理と更新
  • リポジトリ管理

• 自動化管理

  • 自動化の作成と編集
  • 高度な設定オプション：
    • 複数のトリガータイプ
    • 複雑な条件
    • アクションシーケンス
    • 実行モード
  • 既存の自動化を複製、変更
  • 自動化ルールの有効化／無効化
  • 自動化を手動でトリガー

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

• インテリジェントな整理

  • エリアとフロアに基づくデバイスのグループ化
  • 状態の監視と照会
  • スマートなコンテキスト認識
  • 履歴データへのアクセス

• 堅牢なアーキテクチャ

  • 包括的なエラー処理
  • 状態の検証
  • セキュアな API 統合
  • TypeScript の型安全性
  • 広範なテストカバレッジ

前提条件

• Node.js 20.10.0 以降
• NPM パッケージマネージャー
• コンテナ化用の Docker Compose
• 稼働中の Home Assistant インスタンス
• Home Assistant の長期アクセストークン（トークンの取得方法）
• パッケージ管理機能を利用するために HACS をインストール済みであること
• アドオン管理用の Supervisor アクセス

インストール

基本セットアップ

# Clone the repository
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Docker セットアップ（推奨）

このプロジェクトには、さまざまなプラットフォームで簡単にデプロイし、一貫した環境を実現するための Docker サポートが含まれています。

1. リポジトリをクローンします：

   git clone https://github.com/tevonsb/homeassistant-mcp.git
   cd homeassistant-mcp
   

2. 環境を設定します：

   cp .env.example .env
   

   .env ファイルを Home Assistant の設定に合わせて編集します：

   # 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
   

3. Docker Compose でビルドして実行します：

   # Build and start the containers
   docker compose up -d
   
   # View logs
   docker compose logs -f
   
   # Stop the service
   docker compose down
   

4. インストールを確認します： サーバーは http://localhost:3000 で稼働しているはずです。http://localhost:3000/health でヘルスエンドポイントを確認できます。

5. アプリケーションを更新します：

   # 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：環境（production/development）
• 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

設定ファイル

1. 開発：.env.example を .env.development にコピーします
2. 本番環境：.env.example を .env.production にコピーします
3. テスト：.env.example を .env.test にコピーします

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

新しい Home Assistant MCP サーバーを使用するには、Claude Desktop をクライアントとして追加できます。以下を設定に追加してください。この方法では MCP が claude 内で実行され、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

トラブルシューティング

よくある問題

1. Node.js のバージョン (toSorted is not a function)

   • 解決策: Node.js 20.10.0 以降に更新してください

   nvm install 20.10.0
   nvm use 20.10.0
   

2. 接続の問題

   • Home Assistant が実行されていることを確認する
   • HASS_HOST にアクセスできることを確認する
   • トークンの権限を検証する
   • リアルタイム更新のために WebSocket 接続を確保する

3. アドオン管理の問題

   • Supervisor へのアクセスを確認する
   • アドオンの互換性を確認する
   • システムリソースを検証する

4. HACS 統合の問題

   • HACS のインストールを確認する
   • HACS 統合のステータスを確認する
   • リポジトリへのアクセスを検証する

5. 自動化の問題

   • エンティティの可用性を確認する
   • トリガー条件を確認する
   • サービス呼び出しを検証する
   • 実行ログを監視する

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

✅ 完了

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

🚧 進行中

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

コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を実装する
4. 新機能のテストを追加する
5. すべてのテストが通ることを確認する
6. プルリクエストを送信する

リソース

• MCP ドキュメント
• Home Assistant ドキュメント
• HA REST API
• HACS ドキュメント
• TypeScript ドキュメント

ライセンス

MIT ライセンス - LICENSE ファイルを参照してください