Hass MCP

🚀 Home Assistant MCPサーバー

このMCPサーバーは、Home Assistantの機能をAIアシスタントに公開します。Goで構築されており、Claude、Cursor、OpenAIなどのAIクライアントが、Model Context Protocolを通じてスマートホームとやり取りできるようになります。

🚀 クイックスタート

必要条件

• Go 1.24以上（ソースからのビルド時のみ）
• APIアクセスを持つHome Assistantインスタンス
• Home Assistantからの長期アクセストークン

Home Assistantトークンの取得方法

1. Home Assistantインスタンスにアクセスする
2. 左下のプロフィールをクリックする
3. 「Long-Lived Access Tokens」までスクロールする
4. 新しいトークンを作成し、コピーする

インストール

ソースからビルド

git clone https://github.com/achetronic/hass-mcp.git
cd hass-mcp
make build

バイナリはbin/hass-mcp-{os}-{arch}に作成されます。

Docker

docker pull ghcr.io/achetronic/hass-mcp:latest

または、ローカルでビルドする場合は：

make docker-build IMG=your-registry/hass-mcp:latest

✨ 主な機能

• エンティティ管理：Home Assistantのエンティティを照会、検索、制御する
• サービス呼び出し：AIを通じて任意のHome Assistantサービスを実行する
• システムインサイト：概要、ドメインの要約、エンティティの履歴を取得する
• トラブルシューティング：エラーログとオートメーションの状態にアクセスする
• 柔軟なトランスポート：stdio（ローカル）とHTTP（リモート）の両方のモードをサポートする
• 本番環境対応：OAuthサポート、JWT検証、Dockerfile、Helmチャートを含む

📦 インストール

設定

の例に基づいて設定ファイルを作成します。

Stdioモード（ローカルクライアント）

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "stdio"

home_assistant:
  url: "${HA_URL}" # 例: http://homeassistant.local:8123
  token: "${HA_TOKEN}" # 長期アクセストークン

HTTPモード（リモートクライアント）

基本的なHTTPサーバー（プライベートネットワーク）

内部使用または開発用に、認証なしで簡単なHTTPサーバーを実行できます。

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

home_assistant:
  url: "${HA_URL}"
  token: "${HA_TOKEN}"

OAuth 2.1を使用したHTTPサーバー（公開用）

公開用のデプロイメントでは、サーバーはJWT検証付きのOAuth 2.1をサポートしています。これにより、Claude WebやChatGPTなどのリモートAIクライアントからの安全なアクセスが可能になります。

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

home_assistant:
  url: "${HA_URL}"
  token: "${HA_TOKEN}"

middleware:
  jwt:
    enabled: true
    validation:
      strategy: "local" # JWKSを使用して内部でJWTを検証する
      local:
        jwks_uri: "https://keycloak.example.com/realms/mcp-servers/protocol/openid-connect/certs"
        cache_interval: "10s"
        # オプション: JWTクレームを検証するCEL式
        allow_conditions:
          - expression: 'payload.groups.exists(g, g == "home-assistant-users")'

oauth_authorization_server:
  enabled: true
  issuer_uri: "https://keycloak.example.com/realms/mcp-servers"

oauth_protected_resource:
  enabled: true
  resource: "https://hass-mcp.example.com/mcp"
  auth_servers:
    - "https://keycloak.example.com/realms/mcp-servers"
  scopes_supported:
    - openid
    - profile

💡 使用アドバイス

上流のプロキシ（例：Istio）がJWTを検証する場合は、strategy: "external"を使用し、forwarded_headerを設定して、プロキシから検証済みのJWTを受け取ることができます。

⚠️ 重要な注意

環境変数は${VAR}構文でサポートされています。

完全な設定例については、を参照してください。

💻 使用例

ローカルクライアント（Claude Desktop、Cursor、VS Code）

ローカルのAIクライアントには、stdioトランスポートを使用します。クライアントの設定に追加します。

Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "home-assistant": {
      "command": "/path/to/hass-mcp",
      "args": ["--config", "/path/to/config-stdio.yaml"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-token-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "home-assistant": {
      "command": "/path/to/hass-mcp",
      "args": ["--config", "/path/to/config-stdio.yaml"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-token-here"
      }
    }
  }
}

リモートクライアント（Claude Web、OpenAI）

リモートクライアントには、HTTPトランスポートを使用します。

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-token-here"
./hass-mcp --config config-http.yaml

サーバーはデフォルトでポート8080で起動します。使用可能なエンドポイントは設定によって異なります。

📚 ドキュメント

開発

# サーバーを実行する
make run

# コードをフォーマットする
make fmt

# リンターを実行する
make lint

# 自動修正付きでリンターを実行する
make lint-fix

# バイナリをビルドする
make build

# 利用可能なすべてのターゲットを表示する
make help

デプロイメント

Kubernetes

ディレクトリにHelmチャートが提供されています。

# 依存関係を更新する
helm dependency update ./chart

# インストールする
helm install hass-mcp ./chart \
  --set config.home_assistant.url="http://homeassistant.local:8123" \
  --set config.home_assistant.token="your-token-here"

chart/values.yamlの値を環境に合わせて設定してください。

本番環境での推奨事項

• 認証：本番環境では、リバースプロキシ（例：Istio、Traefik）を使用してJWTを検証します。
• OAuth：リモートクライアントの認証にOAuthエンドポイントを有効にします。
• セッションアフィニティ：複数のレプリカを実行する場合は、セッションアフィニティに一貫したハッシュルーターを使用します。
• シークレット：トークンはKubernetesシークレットまたは外部シークレットマネージャーに保存します。

プロジェクト構造

├── cmd/main.go              # アプリケーションのエントリーポイント
├── api/                     # 設定タイプ
├── internal/
│   ├── hass/                # Home Assistant APIクライアント
│   ├── tools/               # MCPツールの実装
│   ├── handlers/            # HTTPエンドポイントハンドラー
│   ├── middlewares/         # HTTP/JWTミドルウェア
│   ├── config/              # 設定の読み込み
│   └── globals/             # アプリケーションコンテキスト
├── docs/                    # 設定例
└── chart/                   # Kubernetes用のHelmチャート

動作原理

flowchart LR
    A[AIアシスタント<br/>Claude、Cursorなど] <-->|MCPプロトコル<br/>stdioまたはHTTP/SSE| B[hass-mcp<br/>サーバー]
    B <-->|REST API| C[Home Assistant<br/>インスタンス]

1. AIアシスタントがMCPを介してhass-mcpに接続します（ローカルクライアントはstdio、リモートクライアントはHTTP/SSE）
2. アシスタントは利用可能なツールを発見し、呼び出すことができます
3. hass-mcpはツールの呼び出しをHome Assistant REST APIリクエストに変換します
4. 結果は構造化された形式でアシスタントに返されます

関連リンク

• Model Context Protocol仕様
• Home Assistant REST API
• mcp-goライブラリ

貢献方法

貢献は歓迎されます。プルリクエストを送信する前に、変更について議論するためのイシューを開いてください。

📄 ライセンス

このプロジェクトはApache 2.0ライセンスの下でライセンスされています。詳細については、LICENSEを参照してください。

📦 利用可能なツール