Skip to main content
Glama

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

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

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

ライセンスNode.jsDockerコンポーズ国立博物館タイプスクリプトテスト範囲

特徴

  • 🎮デバイスコントロール:自然言語で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 build

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

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

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

    git clone https://github.com/jango-blockchained/homeassistant-mcp.git
    cd homeassistant-mcp
  2. 環境を構成する:

    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
  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 : 環境(本番/開発)

  • 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をクライアントとして追加します。以下の設定を追加してください。これは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

トラブルシューティング

よくある問題

  1. Node.js バージョン (

    • 解決策: Node.js 20.10.0+ GXP38 にアップデートする

  2. 接続の問題

    • Home Assistantが動作していることを確認する

    • HASS_HOSTアクセス可能性を確認する

    • トークンの権限を検証する

    • リアルタイム更新のためにWebSocket接続を確保する

  3. アドオン管理の問題

    • スーパーバイザーのアクセスを確認する

    • アドオンの互換性を確認する

    • システムリソースを検証する

  4. HACS統合の問題

    • HACSのインストールを確認する

    • HACS統合ステータスを確認する

    • リポジトリアクセスを検証する

  5. 自動化の問題

    • エンティティの可用性を確認する

    • トリガー条件を確認する

    • サービスコールの検証

    • 実行ログを監視する

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

完了

  • エンティティ、フロア、エリアへのアクセス

  • デバイス制御(ライト、空調、カバー、スイッチ、連絡先)

  • アドオン管理システム

  • HACSによるパッケージ管理

  • 高度な自動化構成

  • 基本的な状態管理

  • エラー処理と検証

  • Dockerコンテナ化

  • Jestテストのセットアップ

  • TypeScript統合

  • 環境変数管理

  • ホームアシスタントAPI統合

  • プロジェクトドキュメント

🚧進行中

  • リアルタイム更新のためのWebSocket実装

  • 強化されたセキュリティ機能

  • ツール構成の最適化

  • パフォーマンスの最適化

  • リソースコンテキストの統合

  • APIドキュメント生成

  • マルチプラットフォームデスクトップ統合

  • 高度なエラー回復

  • カスタムプロンプトテスト

  • macOSとの統合強化

  • 型安全性の改善

  • テスト範囲の拡大

貢献

  1. リポジトリをフォークする

  2. 機能ブランチを作成する

  3. 変更を実装する

  4. 新しい機能のテストを追加する

  5. すべてのテストに合格することを確認する

  6. プルリクエストを送信する

リソース

ライセンス

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

-
security - not tested
A
license - permissive license
-
quality - not tested

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tevonsb/homeassistant-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server