Hass-MCP

Name: Hass-MCP
Author: voska

ローカル

github.com/voskaAI・エージェント3514 日前に更新

リポジトリ

Hass-MCP について

Hass-MCP は、Claude などの LLM から Home Assistant を照会・操作するための MCP サーバーです。AI アシスタントでスマートホームを管理したい利用者に向けており、stdio と Streamable HTTP の両方で動作します。

主な機能

01デバイスやセンサーの状態の照会
02ライトやスイッチなどエンティティの操作
03オートメーションの一覧表示と操作
04履歴、統計、エラーログの取得
05WebSocket API 経由での Lovelace ダッシュボード編集

活用シーン

01AI アシスタントに部屋の温度や機器の状態を問い合わせ
02自然言語によるライトやスイッチの操作
03フィルタ付きエラーログによるオートメーションの調査

MCP 対応

Hass-MCP 自体が MCP サーバーであり、Claude Desktop、Cursor、Claude Code などの MCP クライアントに Home Assistant 関連のツールとプロンプトを stdio または Streamable HTTP で提供します。

#home-automation #mcp #home-assistant #mcp-server

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "hass": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL>",
        "HA_TOKEN": "<HA_TOKEN>"
      }
    }
  }
}

起動コマンドdocker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

設定が必要な環境変数

HA_URL

HA_TOKENシークレット

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

ocivoska/hass-mcpstdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Hass-MCP

Claude やその他の LLM と Home Assistant を連携するための Model Context Protocol（MCP）サーバーです。

概要

Hass-MCP を使うと、Claude などの AI アシスタントが Home Assistant インスタンスと直接やり取りでき、次のことが可能になります。

デバイスやセンサーの状態を取得する
ライト、スイッチ、その他のエンティティを操作する
スマートホームの概要を取得する
オートメーションやエンティティのトラブルシューティングを行う
特定のエンティティを検索する
よくあるタスクのためのガイド付き会話を作成する

スクリーンショット

機能

エンティティ管理：状態の取得、デバイスの操作、エンティティの検索
ドメインの概要：エンティティの種類に関する概要情報を取得
オートメーションのサポート：オートメーションの一覧表示と操作
ガイド付き会話：オートメーションの作成など、よくあるタスクにプロンプトを使用
スマート検索：名前、種類、状態からエンティティを検索
ダッシュボードのライブ編集：Home Assistant の WebSocket API 経由で Lovelace ダッシュボード（カードとビュー）の読み取りと編集が可能です。変更は開いているブラウザーに即座に反映され、自動バックアップとドライランプレビューも利用できます
トークン効率：トークン使用量を最小限に抑える、簡潔な JSON レスポンス

インストール

前提条件

長期間有効なアクセストークンを設定した Home Assistant インスタンス
以下のいずれか：
- Docker（推奨）
- Python 3.13 以降と uv

Claude Desktop のセットアップ

Docker によるインストール（推奨）

Docker イメージを取得します。
```
docker pull voska/hass-mcp:latest
```
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 長期間有効なアクセストークンに置き換えます e. HA_URL を更新します。
- Home Assistant を同じマシンで実行している場合：http://host.docker.internal:8123 を使用します（Mac／Windows の Docker Desktop）
- Home Assistant を別のマシンで実行している場合：実際の IP アドレスまたはホスト名を使用します
f. ファイルを保存し、Claude Desktop を再起動します
Claude Desktop のツールメニューに「Hass-MCP」ツールが表示されます

注：同じマシン上の Docker で Home Assistant を実行している場合、コンテナーから Home Assistant にアクセスできるよう、Docker の引数に --network host を追加する必要がある場合があります。代わりに、host.docker.internal の代わりにマシンの IP アドレスを使用することもできます。

uv／uvx

システムに uv をインストールします。
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 長期間有効なアクセストークンに置き換えます e. HA_URL を更新します。
- Home Assistant を同じマシンで実行している場合：http://host.docker.internal:8123 を使用します（Mac／Windows の Docker Desktop）
- Home Assistant を別のマシンで実行している場合：実際の IP アドレスまたはホスト名を使用します
f. ファイルを保存し、Claude Desktop を再起動します
Claude Desktop のツールメニューに「Hass-MCP」ツールが表示されます

その他の MCP クライアント

Cursor

Cursor Settings > MCP > Add New MCP Server に移動します
フォームに入力します：
- Name：Hass-MCP
- Type：command
- 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 トークンに置き換えます
- Home Assistant インスタンスのアドレスに合わせて HA_URL を更新します
「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 トークンに置き換え、Home Assistant インスタンスのアドレスに合わせて HA_URL を更新します。

HTTP トランスポート（ストリーム可能）

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

注意

HTTP モードでは、ネットワーク経由で Home Assistant の全機能を操作できます。 ポートに接続できる人は誰でも任意のツールを呼び出せます。照明の消灯、ドアの解錠、オートメーションの実行、HA の再起動などが可能です。MCP 仕様には、このサーバーに組み込みの認証レイヤーがまだありません。対応されるまでは、必ず次のいずれかの背後に配置してください：

基本認証またはベアラートークン検証を行うリバースプロキシ（nginx、Caddy、Traefik）

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

ローカルホストのみにバインドする（デフォルトです。何をしているかわからない場合は --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

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

エンドポイント

MCP エンドポイントは /mcp です。クライアントの接続先に http://<host>:<port>/mcp を指定してください。

Smithery / PaaS

サーバーは MCP_PORT に加えて、環境変数 PORT（Smithery の規約）にも対応しています。Smithery へのデプロイには --http モードが必要で、PORT は自動的に読み取られます。

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

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

ローカルの場合：OS の信頼ストアに CA ルートをインストールします（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 で使用できるプロンプトの例を以下に示します。

「リビングの照明の現在の状態は？」
「キッチンの照明をすべて消して」
「主寝室の温度は？」
「ゲストルームにあるものをすべて一覧表示して」
「温度データを含むセンサーをすべて一覧表示して」
「気候関連エンティティの概要を教えて」
「日没時に照明をつけるオートメーションを作成して」
「寝室のモーションセンサーのオートメーションが機能しない理由を調べるのを手伝って」
「リビングに関連するエンティティを検索して」
「Home Assistant のログから直近の ERROR 行を 50 行表示して」
「今日、mqtt インテグレーションでどんな障害が発生した？」
「過去 1 か月の日ごとの電力使用量を表示して」
「先週の火曜日、玄関ドアのセンサーに何があった？」

利用可能なツール

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 の設定を保存するには、長期トークンが管理者ユーザーに属している必要があります。
ストレージモードのみ対応しています。 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 ライセンス

Markdown 対応

ログインしてコメント

基本情報

ライセンス: MIT
作者: voska
言語: python
トランスポート: stdio
掲載日: 2025年3月18日
最終更新: 4 日前

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Hass-MCP

Hass-MCP について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Hass-MCP

概要

スクリーンショット

機能

インストール

前提条件

Claude Desktop のセットアップ

Docker によるインストール（推奨）

uv／uvx

その他の MCP クライアント

Cursor

Claude Code（CLI）

HTTP トランスポート（ストリーム可能）

ローカルでの実行

Docker での実行

エンドポイント

Smithery / PaaS

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

使用例

利用可能なツール

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

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

利用可能なリソース

開発

テストの実行

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？