Home Assistant MCP Server

Home Assistant MCP サーバー

Home Assistant と連携するための Model Context Protocol（MCP） サーバーです。LLM がスマートホームを制御したり、情報を照会したりできます。

機能

• 自然言語を使って Home Assistant のエンティティを照会、制御できます
• MCP 互換クライアント（Claude Desktop など）で利用できます
• 状態管理、サービス呼び出し、履歴などのツールを提供します
• Home Assistant の長期アクセストークンを使用した安全な認証に対応しています
• 複数のトランスポート方式に対応しています（ローカルプロセス用の stdio、リモートクライアント用の SSE）
• Home Assistant を利用できない場合に、テストやデモで使えるモックデータモードがあります

インストール

# Install globally using bun
bun install -g home-assistant-mcp-server

# Or install from source
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

設定

現在のディレクトリに、次の変数を記述した .env ファイルを作成します。

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

環境変数

変数	必須	デフォルト	説明
HASS_URL	はい	-	Home Assistant インスタンスの URL（例：http://homeassistant.local:8123）
HASS_TOKEN	はい	-	Home Assistant の認証に使用する長期アクセストークン
PORT	いいえ	3000	HTTP/SSE トランスポートを使用する場合の HTTP サーバーのポート番号
HASS_MOCK	いいえ	false	"true" に設定すると、Home Assistant に接続せずにテストできるモックデータモードが有効になります

長期アクセストークンを取得する手順は次のとおりです。

1. Home Assistant インスタンスにログインします
2. プロフィールをクリックします（左下）
3. 「Long-Lived Access Tokens」までスクロールします
4. 分かりやすい名前を付けて新しいトークンを作成します
5. トークンの値をコピーします（再表示できません）

使用方法

スタンドアロンサーバーとして実行する

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

Claude Desktop との連携

Claude Desktop で使用するには、次の手順に従います。

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

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. サーバー設定を追加します。

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server"
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here",
        "HASS_MOCK": "true"
      }
    }
  }
}

Home Assistant が稼働している場合は、--mock フラグを削除し、HASS_MOCK を false に設定するだけです。

3. Claude Desktop を再起動します

利用可能なツール

このサーバーは、Home Assistant と連携するための複数のツールを公開します。

• states - エンティティの状態を照会します
• lights - ライトの一覧を表示します
• light - ライトを制御します
• service - Home Assistant のサービスを呼び出します
• history - エンティティの履歴データを取得します
• services - 利用可能なサービスを一覧表示します
• config - Home Assistant の設定を取得します
• domains - 利用可能なドメインを一覧表示します
• error_log - Home Assistant のエラーログを取得します
• devices - Home Assistant 内のすべてのデバイスを取得します

詳しい使用例については、docs/hass-mcp.md を参照してください。

セキュリティ

このサーバーを使用するには、フルアクセス権を持つ Home Assistant アクセストークンが必要です。次のセキュリティに関する推奨事項を検討してください。

• 信頼できるネットワーク上でのみサーバーを実行してください
• サーバーをリモートから公開する場合は HTTPS を使用してください
• .env ファイルを安全に保管し、ソース管理にコミットしないでください
• 可能な場合は、権限を制限したトークンの使用を検討してください

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については LICENSE ファイルを参照してください。