hass-mcp — HiTech Lab エディション

HiTech Lab によってメンテナンスおよび最適化されています ソース: https://github.com/voska/hass-mcp

Hass-MCP

Claude や他の LLM と Home Assistant を統合するための Model Context Protocol (MCP) サーバーです。

概要

Hass-MCP は、Claude などの AI アシスタントが Home Assistant インスタンスと直接やり取りできるようにし、以下の操作を可能にします:

• デバイスやセンサーの状態を照会する

• 照明、スイッチ、その他のエンティティを制御する

• スマートホームの概要を取得する

• オートメーションやエンティティのトラブルシューティングを行う

• 特定のエンティティを検索する

• 一般的なタスク向けのガイド付き会話を作成する

Related MCP server: Hass-MCP

スクリーンショット

特徴

• エンティティ管理: 状態の取得、デバイスの制御、エンティティの検索

• ドメイン概要: エンティティタイプに関する高レベルの情報を取得

• オートメーション対応: オートメーションの一覧表示と制御

• ガイド付き会話: オートメーション作成などの一般的なタスクにプロンプトを使用

• スマート検索: 名前、タイプ、または状態でエンティティを検索

• ライブダッシュボード編集: Home Assistant の WebSocket API 経由で Lovelace ダッシュボード（カードとビュー）を読み取り・編集 — 変更は開いているブラウザに即座に反映され、自動バックアップとドライランプレビューも利用できます

• トークン効率: トークン使用量を最小限に抑えるスリムな JSON レスポンス

インストール

前提条件

• Long-Lived Access Token を持つ Home Assistant インスタンス

• 次のいずれか:

  • Docker（推奨）

  • Python 3.13+ と uv

Claude Desktop での設定

Docker でのインストール（推奨）

1. Docker イメージをプルします:

   docker pull voska/hass-mcp:latest

2. MCP サーバーを Claude Desktop に追加します:

   a. Claude Desktop を開き、Settings に移動します b. Developer > Edit Config に移動します c. claude_desktop_config.json ファイルに次の設定を追加します:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "HA_URL",
           "-e",
           "HA_TOKEN",
           "voska/hass-mcp"
         ],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN を実際の Home Assistant の Long-Lived Access Token に置き換えます e. HA_URL を更新します:

   • Home Assistant を同じマシンで実行している場合: http://host.docker.internal:8123 を使用します（Mac/Windows の Docker Desktop）

   • Home Assistant を別のマシンで実行している場合: 実際の IP またはホスト名を使用します

   f. ファイルを保存し、Claude Desktop を再起動します

3. 「Hass-MCP」ツールが Claude Desktop のツールメニューに表示されるはずです

注記: 同じマシンで Home Assistant を Docker で実行している場合、コンテナが Home Assistant にアクセスできるように Docker の引数に --network host を追加する必要があるかもしれません。あるいは、host.docker.internal の代わりにマシンの IP アドレスを使用してください。

uv/uvx

1. システムに uv をインストールします。

2. MCP サーバーを Claude Desktop に追加します:

   a. Claude Desktop を開き、Settings に移動します b. Developer > Edit Config に移動します c. claude_desktop_config.json ファイルに次の設定を追加します:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "uvx",
         "args": ["hass-mcp"],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN を実際の Home Assistant の Long-Lived Access Token に置き換えます e. HA_URL を更新します:

   • Home Assistant を同じマシンで実行している場合: http://host.docker.internal:8123 を使用します（Mac/Windows の Docker Desktop）

   • Home Assistant を別のマシンで実行している場合: 実際の IP またはホスト名を使用します

   f. ファイルを保存し、Claude Desktop を再起動します

3. 「Hass-MCP」ツールが Claude Desktop のツールメニューに表示されるはずです

他の MCP クライアント

Cursor

1. Cursor の Settings > MCP > Add New MCP Server に移動します

2. フォームに入力します:

   • 名前: Hass-MCP

   • タイプ: command

   • コマンド:

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp

   • YOUR_LONG_LIVED_TOKEN を実際の Home Assistant トークンに置き換えます

   • HA_URL を Home Assistant インスタンスのアドレスに合わせて更新します

3. 「Add」をクリックして保存します

Claude Code（CLI）

Claude Code CLI で使用するには、mcp add コマンドを使用して MCP サーバーを直接追加できます:

Docker を使用する場合（推奨）:

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

YOUR_LONG_LIVED_TOKEN を実際の Home Assistant トークンに置き換え、HA_URL を Home Assistant インスタンスのアドレスに合わせて更新します。

HTTP トランスポート（Streamable）

stdio を使用できないデプロイメント（MCP ゲートウェイの背後で実行する、Smithery でホストする、1 つのサーバーを複数のクライアントで共有する、LibreChat や OpenWebUI のようなネットワークベースのツールから接続する）向けに、Hass-MCP は MCP の streamable HTTP transport をサポートしています。サーバーはステートレスモード（Mcp-Session-Id なし、JSON レスポンス）で動作し、水平スケーリングされたホストに適しています。

[!CAUTION] HTTP モードは Home Assistant の完全な制御をネットワークにさらします。 ポートに到達できる人は誰でも任意のツールを呼び出せます — 照明を消す、ドアのロックを解除する、オートメーションをトリガーする、HA を再起動するなど。このサーバーでは、MCP 仕様にはまだ組み込みの認証レイヤーが搭載されていません。搭載されるまでは、以下のいずれかの背後に配置する必要があります:

• basic-auth または bearer-token 検証を行うリバースプロキシ（nginx、Caddy、Traefik）

• VPN またはゼロトラストネットワーク（Tailscale、WireGuard、Cloudflare Access）

• localhost バインドのみ（デフォルト — --host を変更するのは、何をしているのか理解している場合だけにしてください）

認証なしで :8000 をオープンインターネットに公開しないでください。

ローカルでの実行

uvx を使用:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

サーバーはデフォルトで 127.0.0.1 にバインドします。--host 0.0.0.0 に変更するのは、その前に認証も設定している場合だけにしてください。

Docker での実行

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

--host 0.0.0.0 は Docker 内でポートがブリッジ経由で到達可能になるために必要です。ホストからのみ到達できればよい場合は、公開（-p）を 127.0.0.1:8000:8000 にバインドするか、前面にリバースプロキシを配置してください。

エンドポイント

MCP エンドポイントは /mcp です。クライアントを http://<host>:<port>/mcp に向けてください。

Smithery / PaaS

サーバーは MCP_PORT に加えて PORT 環境変数（Smithery の慣例）も尊重します。Smithery へのデプロイでは --http モードが必要で、PORT を自動的に読み取ります。

カスタム / プライベート CA

Home Assistant インスタンスが独自の CA（step-ca、smallstep、homelab OpenSSL）によって署名された証明書を提供している場合、hass-mcp は TLS を無効にせずにその証明書を検証できます:

• ローカル: CA ルートを OS のトラストストア（macOS Keychain、Windows Cert Store、または Linux の update-ca-certificates）にインストールします。hass-mcp は truststore 経由で自動的にそれを読み取ります。

• Docker 内（または任意のサンドボックス化されたランタイム）: CA ファイルをバインドマウントし、SSL_CERT_FILE をそのファイルに向けます。

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE は設定されている場合、常に OS のストアより優先されます。verify=False は意図的にサポートされていません — 暗号化されていないローカル LAN トラフィックを本当に使用したい場合は HA_URL=http://... を使用してください。

使用例

Hass-MCP をセットアップした後、Claude で使用できるプロンプトの例をいくつか示します:

• 「リビングの照明の現在の状態は？」

• 「キッチンの照明をすべて消して」

• 「主寝室の温度は？」

• 「ゲストルームにあるものをすべてリストアップして」

• 「温度データを含むすべてのセンサーをリストアップして」

• 「気候（climate）エンティティの概要を教えて」

• 「日没時に照明をオンにするオートメーションを作成して」

• 「寝室の人感センサーのオートメーションが機能しない理由のトラブルシューティングを手伝って」

• 「リビングに関連するエンティティを検索して」

• 「Home Assistant のログから最後の 50 行の ERROR を表示して」

• 「今日、mqtt 統合で何が失敗していますか？」

• 「先月の日ごとの電力使用量を表示して」

• 「先週の火曜日に玄関ドアのセンサーで何が起こりましたか？」

利用可能なツール

Hass-MCP は Home Assistant とやり取りするための複数のツールを提供します:

• get_version: Home Assistant のバージョンを取得します

• get_entity: 特定のエンティティの状態を、オプションのフィールドフィルタリング付きで取得します

• entity_action: エンティティに対してアクションを実行します（オン、オフ、トグル）

• list_entities: エンティティのリストを、オプションのドメインフィルタリングと検索付きで取得します

• search_entities_tool: クエリに一致するエンティティを検索します

• domain_summary_tool: ドメインのエンティティの概要を取得します

• list_automations: すべてのオートメーションのリストを取得します

• call_service_tool: 任意の Home Assistant サービスを呼び出します

• restart_ha: Home Assistant を再起動します

• get_history: エンティティの状態履歴を取得します（過去 N 時間）

• get_history_range: エンティティの状態変更履歴を、明示的な日時範囲（start_time / end_time、ISO-8601）で取得します

• get_statistics: エンティティの長期的な集計統計（バケットごとの平均 / 最小 / 最大）を過去 N 時間分取得します — レコーダーの短期保持ウィンドウより古いデータでも動作します

• get_statistics_range: 同じですが、明示的な日時範囲を指定します — 月次 / 年次のトレンドクエリに便利です

• get_error_log: Home Assistant のエラーログを取得します。オプションの level / integration / search_term / lines フィルターをサーバー側で適用できるため、ノイズの多いログが Claude のコンテキストを圧迫しません

• get_entities_by_area: 特定のエリア / 部屋のエンティティをリストアップします

ダッシュボード（Lovelace）の編集

Home Assistant の WebSocket API を介してダッシュボードを読み取り、ライブ編集できます。保存すると、変更は開いているすべてのブラウザに即座に反映されます — 再起動は不要です。

• list_dashboards: ダッシュボードを一覧表示します（デフォルトと任意のユーザーダッシュボード）。各ダッシュボードの url_path と mode（storage / yaml）も表示します

• get_dashboard_config: ダッシュボードの完全な設定を取得します

• set_dashboard_config: ダッシュボードの完全な設定を置き換えます（低レベル）

• add_card / update_card / remove_card / move_card: ビュー内のカードを編集します（ビューはインデックス、またはその path / title で選択します）

• list_view_sections: 「sections」タイプのビューのセクションを一覧表示します

• add_view / remove_view / update_view: ダッシュボードのビューを編集します

• list_dashboard_backups / restore_dashboard: 自動保存前バックアップの一覧表示と、そのバックアップへのロールバック

Sections ビュー: Home Assistant のモダンなビュータイプ（type: sections）は、カードを単一のトップレベルリストではなくセクション内に保存します。そのようなビューでは、list_view_sections を呼び出し、カードツールに section 引数（インデックス、タイトル、または見出し）を渡してください。section なしの sections ビューへのカード編集は、利用可能なセクションのリスト付きで拒否されます — レンダリングされない場所にカードを黙って保存することはありません。

すべての編集ツールは dry_run=true を受け付け、保存せずに結果の設定と変更サマリーをプレビューできます。

重要な注意事項:

• 管理者トークンが必要です。 Lovelace 設定の保存には、Long-Lived Token が管理者ユーザーに属している必要があります。

• ストレージモードのみ。 UI 管理（「storage」）のダッシュボードのみ編集できます。YAML モードのダッシュボードは検出され、明確なメッセージとともに拒否されます — 代わりに YAML ファイルを直接編集してください。

• 設定全体の書き込み。 Home Assistant には部分編集 API はなく、すべての変更はダッシュボード全体の読み取り-変更-書き込みです。高レベルのカード/ビューツールがこれを処理します。

• 自動バックアップ。 書き込みのたびに、現在の設定は HASS_MCP_BACKUP_DIR（デフォルト ~/.hass-mcp/dashboard-backups/）に保存されます。Docker で実行する場合は、このパスにボリュームをマウントしてください。マウントしないと、コンテナが再作成されたときにバックアップが失われます。

ガイド付き会話用のプロンプト

Hass-MCP にはガイド付き会話用のプロンプトがいくつか含まれています:

• create_automation: トリガータイプに基づいてHome Assistantオートメーションを作成するためのガイド

• debug_automation: 動作しないオートメーションのトラブルシューティングヘルプ

• troubleshoot_entity: エンティティの問題を診断する

• routine_optimizer: 使用パターンを分析し、実際の動作に基づいて最適化されたルーチンを提案する

• automation_health_check: すべてのオートメーションをレビューし、競合、冗長性、改善の機会を見つける

• entity_naming_consistency: エンティティ名を監査し、標準化の改善を提案する

• dashboard_layout_generator: ユーザーの好みと使用パターンに基づいて最適化されたダッシュボードを作成する

利用可能なリソース

Hass-MCPは以下のリソースエンドポイントを提供します：

• hass://entities/{entity_id}: 特定のエンティティの状態を取得する

• hass://entities/{entity_id}/detailed: すべての属性を含むエンティティの詳細情報を取得する

• hass://entities: ドメインごとにグループ化されたすべてのHome Assistantエンティティを一覧表示する

• hass://entities/domain/{domain}: 特定のドメインのエンティティのリストを取得する

• hass://search/{query}/{limit}: カスタム結果制限付きでクエリに一致するエンティティを検索する

開発

テストの実行

uv run pytest tests/

ライセンス

MIT License