Home Assistant MCP Server

hass-mcp-server

Home Assistant をフルコントロールできる MCP サーバーです。AI エージェント（GitHub Copilot、Claude など）がダッシュボード、自動化、ファイル、アプリ、エンティティなどを管理するため、HA の設定をご自身で操作する必要はありません。

特長

• ダッシュボード管理 — Lovelace ダッシュボードの作成、更新、削除、およびダッシュボード設定一式のデプロイ
• ファイル管理 — SFTP 経由で HA インスタンス上のファイルをアップロード、読み取り、一覧表示、削除（カスタムカード、画像、HTML ファイルなど）
• 自動化、スクリプト、シーン — 自動化、スクリプト、シーンの完全な CRUD 操作
• 入力ヘルパー — input_boolean、input_number、input_text、input_select、input_datetime、input_button、counter、timer のヘルパーを作成・管理
• アプリ管理 — アプリ（アドオン）のインストール、起動、停止、再起動、アンインストール、設定
• エンティティとサービスの制御 — 状態の照会、サービスの呼び出し、テンプレートのレンダリング、エンティティ／デバイス／エリアのレジストリの参照
• システムツール — システム情報、設定の検証、バックアップ、コアの再起動、エラーログ
• イベントとカレンダーのツール — イベントタイプの一覧表示、イベントの発火、カレンダーの照会
• 状態管理 — エンティティ状態の設定・削除、インテントの処理

REST API、WebSocket API、SSH/SFTP の 3 つの HA トランスポート層を使用する、5 カテゴリーにわたる66 個のツールを備えています。

前提条件

• Home Assistant OS（または Supervisor を備えた任意の HA インストール）
• 長期アクセストークン — HA → プロフィール → セキュリティ → 長期アクセストークンから作成します
• Node.js 20+
• （任意）SSH アプリ — ファイル管理ツールを使用する場合にのみ必要です。アプリストアから「Advanced SSH & Web Terminal」をインストールしてください。

クイックスタート

インストールは不要です。MCP クライアントが npx 経由でサーバーを自動的に実行します。設定をクライアントに追加するだけで、すぐに使用できます。

設定

サーバーは、MCP クライアントの設定ファイルで設定する環境変数を使って構成します。クライアントは起動時にこれらをサーバープロセスに渡すため、システム全体の環境変数を設定する必要はありません。

必須の変数

変数	説明	例
HA_URL	Home Assistant のベース URL	http://homeassistant.local:8123
HA_TOKEN	長期アクセストークン	(HA のプロフィール → セキュリティから取得)

オプションの変数（ファイル管理用）

ファイル管理ツールを使うには SSH アクセスが必要です。詳しくは、以下のSSH の設定をご覧ください。

変数	説明	例
HA_SSH_HOST	SSH ホスト名	homeassistant.local
HA_SSH_PORT	SSH ポート（デフォルト：22）	22
HA_SSH_USER	SSH ユーザー名（rootである必要があります）	root
HA_SSH_KEY_PATH	SSH 秘密鍵へのパス	OS ごとの例をご覧ください
HA_SSH_PASSWORD	SSH パスワード（鍵の代わりに使用）	(お使いのパスワード)

長期アクセストークンの取得

1. Home Assistant の UI を開きます
2. プロフィールアイコンをクリックします（左下）
3. セキュリティタブの長期アクセストークンまでスクロールします
4. トークンを作成をクリックし、名前を付けてトークンをコピーします

MCP クライアントのセットアップ

以下からお使いの MCP クライアントのセットアップ方法を選択してください。いずれの場合も、設定を追加すると、クライアントが npx 経由でサーバーを自動的にダウンロードして実行します。

ヒント： ファイル管理ツールが不要な場合は、HA_SSH_* 変数を省略できます。サーバーは SFTP なしで起動し、ファイルツールを使おうとした場合にのみ失敗します。

VS Code（GitHub Copilot）

オプション A：拡張機能をインストールする（推奨）

最も簡単な方法は、VS Code Marketplace からHome Assistant MCP Server拡張機能をインストールすることです。MCP サーバーが自動的に登録され、認証情報は安全に保存されます。

1. Marketplace から拡張機能をインストールします（または、拡張機能ビューで「Home Assistant MCP Server」を検索します）。
2. 設定 → homeAssistantMcp.urlで Home Assistant の URL を設定します。
3. コマンドパレット（Ctrl+Shift+P）から**「Home Assistant MCP: Set Access Token」**を実行します。
4. MCP サーバーが Copilot Chat に自動的に表示されます。

ファイル管理を使う場合は、SSH 設定（homeAssistantMcp.ssh.*）を構成し、必要に応じて**「Home Assistant MCP: Set SSH Password」**を実行します。

オプション B：mcp.jsonからワンクリックでインストール

この README の上部にあるバッジをクリックするか、以下のリンクを使用します。VS Code から Home Assistant の URL とアクセストークンの入力を求められます。

オプション C：mcp.jsonを手動で設定

ワークスペースに.vscode/mcp.jsonを作成するか、グローバルにアクセスできるようにユーザー設定に追加します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ha-url",
      "description": "Home Assistant base URL (e.g. http://homeassistant.local:8123)"
    },
    {
      "type": "promptString",
      "id": "ha-token",
      "description": "Home Assistant long-lived access token",
      "password": true
    }
  ],
  "servers": {
    "home-assistant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "${input:ha-url}",
        "HA_TOKEN": "${input:ha-token}"
      }
    }
  }
}

SSH を使用する場合（ファイル管理ツール用）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ha-url",
      "description": "Home Assistant base URL (e.g. http://homeassistant.local:8123)"
    },
    {
      "type": "promptString",
      "id": "ha-token",
      "description": "Home Assistant long-lived access token",
      "password": true
    }
  ],
  "servers": {
    "home-assistant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "${input:ha-url}",
        "HA_TOKEN": "${input:ha-token}",
        "HA_SSH_HOST": "homeassistant.local",
        "HA_SSH_USER": "root",
        "HA_SSH_KEY_PATH": "/home/you/.ssh/ha_ed25519"
      }
    }
  }
}

Claude Desktop

Claude Desktop の設定ファイルを編集します。

OS	設定ファイルのパス
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json を編集します。

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

その他の MCP クライアント

stdio サーバーに対応している MCP クライアントであれば使用できます。コマンドに npx を指定し、引数に -y @jarahkon/hass-mcp-server@latest を指定して、env ブロックに HA_URL と HA_TOKEN を渡します。

SSH の設定（ファイル管理用）

ファイル管理ツール（ha_upload_file、ha_read_file、ha_list_files など）には、Home Assistant インスタンスへの SSH アクセスが必要です。

1. Home Assistant に SSH アプリをインストールする

1. HA で 設定 → アプリ → アプリストア に移動します
2. Advanced SSH & Web Terminal をインストールします
3. アプリの設定で、ユーザー名を root に設定し（SFTP に必要）、sftp: true を有効にします
4. 認証を設定します。パスワードを設定するか、公開鍵を authorized_keys に追加します（推奨）
5. アプリを起動し、ログを確認して正常に起動したことを確認します

2. SSH キーを生成する（推奨）

キー認証はパスワードよりも安全です。

# Generate a key pair (leave passphrase empty for automated use)
ssh-keygen -t ed25519 -f ~/.ssh/ha_ed25519 -C "ha-mcp-server"

これにより、~/.ssh/ha_ed25519（秘密鍵）と ~/.ssh/ha_ed25519.pub（公開鍵）が作成されます。

公開鍵の内容を、HA のアプリ設定に追加します。

ssh:
  username: root
  password: ""
  authorized_keys:
    - "ssh-ed25519 AAAA...contents of ha_ed25519.pub..."
  sftp: true

3. MCP クライアント設定に SSH 変数を追加する

MCP クライアント設定の env ブロックで、HA_URL と HA_TOKEN に加えて、次の環境変数を追加します。

"HA_SSH_HOST": "homeassistant.local",
"HA_SSH_USER": "root",
"HA_SSH_KEY_PATH": "/home/you/.ssh/ha_ed25519"

パスワード認証を使用する場合は、次のようにします。

"HA_SSH_HOST": "homeassistant.local",
"HA_SSH_USER": "root",
"HA_SSH_PASSWORD": "your_ssh_password_here"

SSH キーのパスの例

OS	HA_SSH_KEY_PATH の例
Windows	C:/Users/you/.ssh/ha_ed25519
macOS	/Users/you/.ssh/ha_ed25519
Linux	/home/you/.ssh/ha_ed25519

ツール一覧

ダッシュボード（6 ツール）

ツール	説明
ha_list_dashboards	すべての Lovelace ダッシュボードを一覧表示します
ha_create_dashboard	url_path、タイトル、アイコンを指定して新しいダッシュボードを作成します
ha_update_dashboard	ダッシュボードのプロパティ（タイトル、アイコン、サイドバーの表示状態）を更新します
ha_delete_dashboard	ID を指定してダッシュボードを削除します
ha_get_dashboard_config	ダッシュボードの Lovelace 設定 JSON 全体を取得します
ha_save_dashboard_config	完全な Lovelace 設定をダッシュボードにデプロイします

ファイル（7 ツール）— SSH が必要

ツール	説明
ha_list_files	HA のディレクトリ内のファイルを一覧表示します（/config/ からの相対パス）
ha_read_file	HA からファイルの内容を読み取ります
ha_upload_file	SFTP 経由でローカルファイルを HA にアップロードします
ha_upload_file_content	文字列の内容を HA 上のファイルに直接書き込みます
ha_delete_file	HA 上のファイルを削除します（安全なディレクトリに制限）
ha_mkdir	HA 上にディレクトリを作成します
ha_file_exists	HA 上にファイルまたはディレクトリが存在するか確認します

オートメーション、スクリプト、シーン、ヘルパー（17 ツール）

ツール	説明
ha_list_automations	すべてのオートメーションを一覧表示します
ha_get_automation	ID を指定して特定のオートメーションの設定を取得します
ha_create_automation	新しいオートメーションを作成します
ha_update_automation	既存のオートメーションを更新します
ha_delete_automation	オートメーションを削除します
ha_list_scripts	すべてのスクリプトを一覧表示します
ha_create_script	新しいスクリプトを作成します
ha_update_script	既存のスクリプトを更新します
ha_delete_script	スクリプトを削除します
ha_list_scenes	すべてのシーンを一覧表示します
ha_create_scene	新しいシーンを作成します
ha_update_scene	既存のシーンを更新します
ha_delete_scene	シーンを削除します
ha_list_helpers	すべての入力ヘルパー（ブール値、数値など）を一覧表示します
ha_create_helper	任意の種類の入力ヘルパーを作成します
ha_update_helper	既存のヘルパーを更新します
ha_delete_helper	ヘルパーを削除します

アプリとシステム（18 個のツール）

ツール	説明
ha_list_addons	インストール済みのすべてのアプリとステータスを一覧表示します
ha_addon_info	特定のアプリの詳細情報を取得します
ha_install_addon	スラッグを指定してアプリをインストールします
ha_start_addon	アプリを起動します
ha_stop_addon	アプリを停止します
ha_restart_addon	アプリを再起動します
ha_uninstall_addon	アプリをアンインストールします
ha_addon_options	アプリの設定オプションを取得または設定します
ha_system_info	システム情報（コア、OS、スーパーバイザー、ホスト）を取得します
ha_check_config	再読み込みの前に HA の設定を検証します
ha_create_backup	全体または一部のバックアップを作成します
ha_list_backups	すべてのバックアップを一覧表示します
ha_restart_core	Home Assistant のコアを再起動します
ha_check_api	HA API にアクセスでき、応答しているか確認します
ha_get_config	HA の設定（場所、単位、バージョン、コンポーネント）を取得します
ha_update_core_config	コアの設定（内部／外部 URL、場所、単位）を更新します
ha_get_components	読み込み済みのすべての HA インテグレーション／コンポーネントを一覧表示します
ha_get_error_log	Home Assistant のエラーログの内容を取得します

エンティティとサービス（18 個のツール）

ツール	説明
ha_get_states	すべてのエンティティの状態を取得します（ドメインによる絞り込みは任意）
ha_get_entity	特定のエンティティの状態と属性をすべて取得します
ha_call_service	任意の HA サービスを呼び出します（turn_on、turn_off、notify など）
ha_list_services	ドメインごとに利用可能なサービスを一覧表示します
ha_render_template	Jinja2 テンプレートをレンダリングします
ha_list_entity_registry	エンティティレジストリからエンティティを一覧表示します
ha_list_devices	すべてのデバイスを一覧表示します
ha_list_areas	すべてのエリア（部屋）を一覧表示します
ha_create_area	新しいエリアを作成します
ha_get_history	指定した期間のエンティティの状態履歴を取得します
ha_get_logbook	ログブックのエントリー（アクティビティログ）を取得します。エンティティによる絞り込みは任意です
ha_get_events	利用可能なすべてのイベントタイプを一覧表示します
ha_fire_event	オートメーションを起動するカスタムイベントを発生させます
ha_set_state	エンティティの状態を設定または作成します（仮想センサー、上書き）
ha_delete_state	エンティティの状態を削除します
ha_get_calendars	すべてのカレンダーエンティティを一覧表示します
ha_get_calendar_events	特定のカレンダーからイベントを取得します
ha_handle_intent	会話／音声インテントを処理します

アーキテクチャ

このサーバーは、Home Assistant との通信に 3 つのトランスポート層を使用します。

層	用途	ライブラリ
REST API (/api/...)	サービス呼び出し、状態、履歴、テンプレート、Supervisor プロキシ、オートメーション／スクリプト／シーンの CRUD	組み込みの fetch
WebSocket API (/api/websocket)	ダッシュボードの CRUD、ヘルパーの CRUD、エンティティレジストリ	ws
SSH/SFTP	HA ファイルシステム上のファイルのアップロード／ダウンロード／一覧表示／削除	ssh2-sftp-client

src/
├── index.ts              # MCP server entry point, registers all tools
├── config.ts             # Environment variable parsing and validation
├── ha/
│   ├── rest-client.ts    # REST API client with auth header
│   ├── ws-client.ts      # WebSocket client with auto-reconnect
│   └── sftp-client.ts    # SFTP client with path safety checks
└── tools/
    ├── dashboards.ts     # 6 dashboard tools
    ├── files.ts          # 7 file management tools
    ├── automations.ts    # 17 automation/script/scene/helper tools
    ├── addons.ts         # 18 app and system tools
    └── entities.ts       # 18 entity and service tools

vscode-extension/         # VS Code Marketplace extension wrapper
└── src/
    └── extension.ts      # Registers MCP server via mcpServerDefinitionProviders API

セキュリティに関する注意事項

• SFTP のパス制限：読み取り操作は /config/ 以下のどこでも許可されます。書き込みと削除の操作は、安全なサブディレクトリ（www/、custom_components/、themes/、blueprints/、scripts/、automations/）と特定のファイル（configuration.yaml、automations.yaml、scripts.yaml、scenes.yaml）に制限されます。deps/ や .storage/ などのシステムディレクトリへの書き込み操作はブロックされます。
• トークンのセキュリティ：.env ファイルをコミットしないでください。.gitignore で除外済みです。
• SSH 認証：パスワードよりも SSH 鍵認証（HA_SSH_KEY_PATH）を優先してください。秘密鍵やパスワードをソース管理にコミットしないでください。

ライセンス

MIT