slhad-aha-mcp

AHA Model Context Protocol (MCP) サーバー

クイックインストールリンク

STDIO

その他

IDE を使わずにテストするのにとても便利です

AHA は Another Home Assistant MCP Server の略です

このリポジトリは、Home Assistant と MCP クライアントの間をつなぐ、Home Assistant 用の Model Context Protocol（MCP）サーバーを実装しています。

このサーバーを使うと、次のことができます。

• Home Assistant エンティティ（ライト、センサー、スイッチなど）の一覧表示とクエリ
• エンティティの状態の取得と更新
• Home Assistant サービスの呼び出し（例：デバイスのオン／オフ）
• オートメーションの管理：一覧表示、作成、更新、検証
• エンティティレジストリへのアクセスと更新
• Lovelace ダッシュボードの統合と更新
• Home Assistant 設定の検証
• プレフィックスまたは正規表現によるエンティティの検索
• エンティティのソースおよびレジストリ情報へのアクセス

このサーバーは、複数のトランスポート方式に対応しています。

• STDIO：従来型の MCP クライアント通信（デフォルト）
• Server-Sent Events（SSE）：ウェブベースのリアルタイム通信
• Streamable HTTP：ウェブ統合向けの HTTP ベース MCP 通信

目次

• AHA Model Context Protocol (MCP) サーバー
  • クイックインストールリンク
  • AHA は Another Home Assistant MCP Server の略です
  • 目次
  • 動機
  • 機能
  • 利用可能なツール
    • ツールのドキュメント生成
  • プロジェクト構成
  • 例：MCP サーバーの実行
    • 1. STDIO トランスポートで実行（デフォルト）
    • 2. Server-Sent Events（SSE）トランスポートで実行
    • 3. Streamable HTTP トランスポートで実行
    • 4. SSE サーバーをすばやく起動
    • 5. Podman/Docker で実行 - STDIO トランスポート
    • 6. Podman/Docker で実行 - HTTP/SSE サーバー
    • 環境変数
  • はじめに
    • 前提条件
    • インストール
    • サーバーの実行
    • テストの実行
    • Docker の使用方法
  • コントリビューション
  • ライセンス

動機

Home Assistant 向けの既存の MCP サーバー実装を調べる中で、次のことが分かりました。

• 多くのリポジトリでは、ビルド可能または動作する Docker イメージが提供されておらず、デプロイが困難、あるいは不可能でした。
• README ファイルに記載された機能やプロトコルを、実際には実装していないプロジェクトがいくつかありました。
• 古くなっていたり、メンテナンスされていなかったり、明確なドキュメントやテストカバレッジが不足していたりするソリューションもありました。

このプロジェクトは、実用性を重視し、シンプルな Docker サポートを備えた、信頼性の高い完全に機能する MCP サーバーを提供することで、こうした課題に対処することを目指しています。

特別な謝辞： このプロジェクトのドキュメントの大部分は、AI によって生成または支援されています。これはサイドプロジェクトであるため（開発者として働いていますが）、楽しく実用的な機能の開発に注力し、すべてを手作業で書くよりも、十分に良ければ生成されたドキュメントをレビューして採用することを好みます。

機能

• Home Assistant クライアントとの連携
• エンティティのレジストリと管理
• オートメーションと設定用の MCP エンドポイント
• Lovelace ダッシュボードのサポート
• 複数のトランスポートオプション：stdio、Server-Sent Events（SSE）、Streamable HTTP
• テストに Vitest を使用する TypeScript コードベース
• 簡単にデプロイできる Docker サポート

利用可能なツール

この MCP サーバーは、Home Assistant と連携するための包括的なツールを提供します。次のような操作が可能です。

• オートメーション管理：オートメーションの作成、更新、削除、トレース
• エンティティ操作：Home Assistant エンティティの照会と操作
• サービス呼び出し：Home Assistant サービスの実行
• 設定：Home Assistant 設定の検証と管理
• レジストリへのアクセス：エンティティおよびデバイスのレジストリへのアクセス
• 設定エントリーフロー用ヘルパー：Home Assistant 統合フローの作成と管理

⚠️ トークンコストに関する警告

重要： 各ツールの定義は、使用していない場合でも LLM のコンテキストでトークンを消費します！update-lovelace-config などの一部のツールだけで、4,000 トークン以上を消費することがあります。不要なツールを除外して、トークン消費を抑え、会話の効率を最大化することを検討してください。

利用可能なすべてのツールの詳細な説明とパラメーターについては、**ツールのドキュメント**を参照してください。

ツールのドキュメントの生成

ツールのドキュメントは MCP サーバーから自動生成されます。

npm run generate-docs

このコマンドは次の処理を行います。

1. inspector を使用して、MCP サーバーから利用可能なすべてのツールを抽出します
2. 包括的な Markdown ドキュメントファイル（tools.md）を生成します
3. 一時ファイルを削除します

注： ツールのドキュメントによると、このサーバーは包括的な Home Assistant 連携のために、現在39 個のツールを提供しています。

プロジェクトの構成

• src/ - メインのソースコード
  • hass/ - Home Assistant クライアントとヘルパー
  • server/ - MCP サーバーの実装
  • mcpTransports.ts - トランスポート層の実装（HTTP、SSE）
• tests/ - テストファイルと Home Assistant 設定の例
• scripts/ - ビルドとドキュメント生成用のスクリプト
• Dockerfile - コンテナ化のサポート
• package.json - プロジェクトの依存関係とスクリプト
• tsconfig.json - TypeScript の設定
• vitest.config.ts - Vitest テストランナーの設定

例：MCP サーバーの実行

MCP サーバーは複数のトランスポート方式をサポートしています。mcp_settings.json と同じコマンドおよび引数の構成で実行できます。

1. STDIO トランスポートで実行（デフォルト）

stdio を介して従来の MCP クライアントと連携する場合（サーバーは MCP クライアントによって起動されます）。

{
  "type": "stdio",
  "command": "tsx",
  "args": [
    "c:/dev/git/aha-mcp/src/index.ts"
  ],
  "env": {
    "LIMIT_RESOURCES": "-1",
    "RESOURCES_TO_TOOLS": "true",
    "DEBUG": "true",
    "HASS_URL": "https://your-home-assistant.local:8123",
    "HASS_ACCESS_TOKEN": "<your_token_here>"
  }
}

2. Server-Sent Events（SSE）トランスポートで実行

SSE ベースの MCP 通信を行うには、サーバーを別途実行してから、URL 経由で接続するように MCP クライアントを設定する必要があります。

ステップ 1：SSE サーバーを起動する

# Start the server with SSE transport using npm script
HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

# Or with additional configuration
RESOURCES_TO_TOOLS=true DEBUG=true HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

ステップ 2：URL 経由で接続するように MCP クライアントを設定する

{
  "url": "http://localhost:8081/sse",
  "alwaysAllow": [
    // your allowed tools here
  ]
}

3. Streamable HTTP トランスポートで実行する

HTTP ベースの MCP 通信では、サーバーを個別に起動してから、URL 経由で接続するよう MCP クライアントを設定する必要があります。

ステップ 1：HTTP サーバーを起動する

# Start the server with streamable HTTP transport using npm script
HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:http

ステップ 2：URL 経由で接続するよう MCP クライアントを設定する

{
  "url": "http://localhost:8081/mcp",
  "alwaysAllow": [
    // your allowed tools here
  ]
}

4. SSE サーバーをすばやく起動する

npm スクリプトで SSE サーバーを直接起動します。

# Set your Home Assistant credentials first
export HASS_URL=https://your-home-assistant.local:8123
export HASS_ACCESS_TOKEN=<your_token_here>

# Start SSE server with RESOURCES_TO_TOOLS enabled
RESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

次のように MCP クライアントを設定します。

{
  "url": "http://localhost:3000/sse"
}

5. Podman/Docker で実行する - STDIO トランスポート

コンテナーで STDIO トランスポートを使用する場合：

{
  "type": "stdio",
  "command": "podman",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "HASS_URL=https://your-home-assistant.local:8123",
    "-e",
    "HASS_ACCESS_TOKEN=<your_token_here>",
    "ghcr.io/slhad/aha-mcp:latest"
  ]
}

6. Podman/Docker で実行する - HTTP/SSE サーバー

HTTP/SSE トランスポートでは、サーバーをコンテナー内で個別に実行します。

ステップ 1：サーバーコンテナーを起動する

# For SSE transport
podman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- sse

# For HTTP transport  
podman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- http

ステップ 2：MCP クライアントを設定する

{
  "url": "http://localhost:3000/sse",  // for SSE
  // or
  "url": "http://localhost:3000/mcp"   // for HTTP
}

<your_token_here> を実際の Home Assistant アクセストークンに置き換えてください。

環境変数

次の環境変数を設定して、MCP サーバーを構成できます。

• HASS_URL（必須）：Home Assistant インスタンスの URL。例：https://your-home-assistant.local:8123（コード内のデフォルト値：http://localhost:8123）
• HASS_ACCESS_TOKEN（必須）：Home Assistant の長期有効アクセストークン。これを設定しないとサーバーは起動しません。
• DEBUG：デバッグログを有効にするには true に設定します。デフォルト値：false。
• RESOURCES_TO_TOOLS：リソースをツールにマッピングするには true に設定します。デフォルト値：false。
  • 詳細な説明： このオプションを有効にすると、Home Assistant のリソース（エンティティ、自動化、サービスなど）が、MCP クライアント向けの個別のツールとして公開されます。これは、汎用的なリソースクエリではなく、ツールベースのインターフェース経由でしかサーバーとやり取りできないクライアントやエージェントに特に役立ちます。こうしたクライアントが Home Assistant の機能を個別に呼び出し可能なツールとして検出して使用できるようになり、ツールが制限された環境での互換性と使いやすさが向上します。
• LIMIT_RESOURCES：サーバーが返すリソース数の上限を設定します。デフォルト値：無制限。

**注：**サーバーのトランスポート方式は、環境変数ではなくコマンドライン引数（sse または http）で指定するようになりました。

はじめに

前提条件

• Node.js（v18 以降を推奨）
• Docker（任意、コンテナーでデプロイする場合）

インストール

npm install

サーバーの実行

STDIO トランスポートの場合（MCP クライアントによって起動）：

# Set environment variables and run with npm
npm start

HTTP/SSE トランスポートの場合（サーバーを個別に実行）：

# Run SSE server on port 8081
npm run start:local:sse

# Run HTTP server on port 8081:8081
npm run start:local:http

# Quick SSE server startup with environment variables
RESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

次の URL で接続するよう MCP クライアントを設定します。

• SSE："url": "http://localhost:3000/sse"
• HTTP："url": "http://localhost:8080/mcp"

テストの実行

npm run test:short

注： 現在、ユニットテストはモックを使用せず、実際の Home Assistant インスタンスに対して実行されます。そのため、テストを正常に実行するには、稼働中の Home Assistant サーバーと有効な認証情報が必要です。

Docker の使用方法

Docker コンテナー内でサーバーをビルドして実行します。

# Build the container
npm run docker

次に、以下の手順に従います。

• Stdio
• HTTP/SSE

HTTP/SSE モードでは、適切な URL で接続するよう MCP クライアントを設定します。

• SSE："url": "http://localhost:3000/sse"
• HTTP："url": "http://localhost:8081/mcp"

コントリビューション

プルリクエストを歓迎します。大きな変更を加える場合は、まず issue を作成して、変更したい内容についてご相談ください。

ライセンス

詳細は LICENSE を参照してください。