ホームアシスタントMCP

ホームアシスタントモデルコンテキストプロトコル（MCP）

AI アシスタントが Home Assistant と対話するための標準化されたプロトコル。スマートホームデバイスを制御するための安全で型付けされた拡張可能なインターフェースを提供します。

概要

モデルコンテキストプロトコル (MCP) サーバーは、AI モデル (Claude、GPT など) と Home Assistant 間のブリッジとして機能し、AI アシスタントが次のことを実行できるようにします。

Home Assistantデバイスでコマンドを実行する
スマートホームに関する情報を取得する
長時間実行操作のストリーム応答
パラメータと入力を検証する
一貫したエラー処理を提供する

特徴

モジュラーアーキテクチャ- トランスポート、ミドルウェア、ツール間の明確な分離
型付きインターフェース- 開発者エクスペリエンスを向上させるために完全に TypeScript 型付けされています
複数のトランスポート:
- CLI統合のための標準I/O （stdin/stdout）
- ストリーミング用のサーバー送信イベントをサポートするHTTP/REST API
ミドルウェアシステム- 検証、ログ記録、タイムアウト、エラー処理
組み込みツール:
- 照明制御（明るさ、色など）
- 気候制御（サーモスタット、HVAC）
- 今後もさらに続きます...
拡張可能なプラグインシステム- 新しいツールや機能を簡単に追加できます
ストリーミングレスポンス- 長時間実行操作のサポート
パラメータ検証- Zodスキーマの使用
Claude & Cursor 統合- AI アシスタント用の既成ユーティリティ

はじめる

前提条件

Node.js 16以上
Home Assistant インスタンス (またはテスト用にモック実装を使用することもできます)

インストール

# Clone the repository
git clone https://github.com/your-repo/homeassistant-mcp.git

# Install dependencies 
cd homeassistant-mcp
npm install

# Build the project
npm run build

サーバーの実行

# Start with standard I/O transport (for AI assistant integration)
npm start -- --stdio

# Start with HTTP transport (for API access)
npm start -- --http

# Start with both transports
npm start -- --stdio --http

構成

環境変数または.envファイルを使用してサーバーを構成します。

# Server configuration
PORT=3000
NODE_ENV=development

# Execution settings
EXECUTION_TIMEOUT=30000
STREAMING_ENABLED=true

# Transport settings
USE_STDIO_TRANSPORT=true
USE_HTTP_TRANSPORT=true

# Debug and logging
DEBUG_MODE=false
DEBUG_STDIO=false
DEBUG_HTTP=false
SILENT_STARTUP=false

# CORS settings
CORS_ORIGIN=*

建築

MCP サーバーは階層型アーキテクチャで構築されています。

トランスポート層- 通信プロトコル（stdio、HTTP）を処理します
ミドルウェア層- パイプラインを通じてリクエストを処理する
ツールレイヤー- 特定の機能を実装する
リソース層- ステートフルリソースを管理する

ツール

ツールはMCPサーバーに機能を追加するための主な手段です。各ツールは以下の機能を備えています。

ユニークな名前を持つ
型付きパラメータを受け入れる
入力された結果を返します
部分的な結果をストリーミングできる
入力と出力を検証する

ツール登録の例:

import { LightsControlTool } from "./tools/homeassistant/lights.tool.js";
import { ClimateControlTool } from "./tools/homeassistant/climate.tool.js";

// Register tools
server.registerTool(new LightsControlTool());
server.registerTool(new ClimateControlTool());

API

HTTP トランスポートで実行する場合、サーバーは JSON-RPC 2.0 API を提供します。

POST /api/mcp/jsonrpc - ツールを実行する
GET /api/mcp/stream - リアルタイム更新のために SSE ストリームに接続します
GET /api/mcp/info - サーバー情報を取得する
GET /health - ヘルスチェックエンドポイント

AIモデルとの統合

クロード・インテグレーション

import { createClaudeToolDefinitions } from "./mcp/index.js";

// Generate Claude-compatible tool definitions
const claudeTools = createClaudeToolDefinitions([
  new LightsControlTool(),
  new ClimateControlTool()
]);

// Use with Claude API
const messages = [
  { role: "user", content: "Turn on the lights in the living room" }
];

const response = await claude.messages.create({
  model: "claude-3-opus-20240229",
  messages,
  tools: claudeTools
});

カーソル統合

Cursor で Home Assistant MCP サーバーを使用するには、 .cursor/config/config.jsonファイルに次のコードを追加します。

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

この構成:

stdioトランスポートでMCPサーバーを実行します
すべてのstderr出力を/dev/nullにリダイレクトします
grepを使用して{"jsonrpc":"2.0"を含む行をstdoutでフィルタリングし、クリーンなJSON-RPC出力を確保します。

カーソル統合のトラブルシューティング

カーソルで MCP サーバーを使用しているときに「クライアントの作成に失敗しました」というエラーが発生した場合:

カーソル設定で正しいコマンドと引数を使用していることを確認してください
- bashスクリプトのアプローチは、有効なJSON-RPCメッセージのみがカーソルに到達することを保証する。
- 接続する前に、 bun run buildを実行してサーバーが構築されていることを確認してください。
サーバーが JSON-RPC メッセージを標準出力に適切に出力していることを確認します。
bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt
次に、json_only.txt を調べて、有効な JSON-RPC メッセージのみが含まれていることを確認します。
grep がシステムにインストールされていることを確認してください (ほとんどのシステムではデフォルトで利用できるはずです)
次のコマンドでサーバーを再構築してみてください。
bun run build
環境変数でDEBUG_STDIO=true設定してデバッグモードを有効にします。

問題が解決しない場合は、次の方法を試してください。

カーソルの再起動
カーソルのキャッシュをクリアする (ヘルプ > 開発者 > キャッシュをクリアして再読み込み)
Node.js で同様のアプローチを使用します。
{ "command": "bash", "args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"] }

ライセンス

マサチューセッツ工科大学

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

Home Assistant 用の MCP サーバー 🏠🤖

概要🌐

MCP（モデル・コンテキスト・プロトコル）サーバーは、Home Assistant用の軽量統合ツールで、デバイスの管理と自動化のための柔軟なインターフェースを提供します。高速、安全、そして使いやすさを追求して設計されています。最高のパフォーマンスを実現するためにBunで構築されています。

コア機能 ✨

🔌 REST API経由の基本的なデバイス制御
📡 状態更新のための WebSocket/Server-Sent Events (SSE)
🤖 シンプルな自動化ルール管理
🔐 JWTベースの認証
🔄 Claude や他の AI アシスタントとの統合のための標準 I/O (stdio) トランスポート

なぜバン？🚀

私が Bun をランタイムとして選択したのは、いくつかの重要な利点があるためです。

⚡驚異的な高速パフォーマンス
- Node.jsより最大4倍高速
- 組み込みのTypeScriptサポート
- 最適化されたファイルシステム操作
🎯オールインワンソリューション
- パッケージマネージャー (npm/yarn よりも高速)
- Bundler（Webpackは不要）
- テストランナー（組み込みテスト）
- TypeScriptトランスパイラ
🔋組み込み機能
- SQLite3 ドライバー
- .envファイルの読み込み
- WebSocketクライアント/サーバー
- ファイルウォッチャー
- テストランナー
💾資源効率が良い
- メモリ使用量の削減
- より速いコールドスタート
- CPU使用率の向上
🔄 Node.js の互換性
- ほとんどのnpmパッケージを実行
- Express/Fastifyと互換性あり
- ネイティブ Node.js API

前提条件 📋

🚀 Bun ランタイム(v1.0.26+)
🏡ホームアシスタントインスタンス
🐳 Docker（オプション、デプロイメントには推奨）
🖥️ Node.js 18+ (オプション、音声機能用)
🎮 CUDA 対応の NVIDIA GPU（オプション、音声処理を高速化）

クイックスタート 🚀

リポジトリをクローンする:

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

環境を設定します。

# Make my setup script executable
chmod +x scripts/setup-env.sh

# Run setup (defaults to development)
./scripts/setup-env.sh

# Or specify an environment:
NODE_ENV=production ./scripts/setup-env.sh

# Force override existing files:
./scripts/setup-env.sh --force

設定を構成します。

Home Assistantの詳細を.envファイルで編集する
必須: HASS_TOKEN (長期アクセストークン) を追加します

Docker でビルドして起動します。

# Standard build
./docker-build.sh

# Launch:
docker compose up -d

Docker ビルドオプション 🐳

私の Docker ビルドスクリプト ( docker-build.sh ) は、さまざまな構成をサポートしています。

1. 標準ビルド

./docker-build.sh

基本的なMCPサーバー機能
REST APIとWebSocketのサポート
音声機能なし

2. 音声対応ビルド

./docker-build.sh --speech

ウェイクワード検出機能を搭載
音声テキスト変換機能
必要なイメージをプルします:
- onerahmet/openai-whisper-asr-webservice
- rhasspy/wyoming-openwakeword

3. GPUアクセラレーションビルド

./docker-build.sh --speech --gpu

すべての音声特徴
CUDA GPUアクセラレーション
より高速な処理のために最適化
パフォーマンス向上のためのFloat16計算型

ビルド機能

🔄自動リソース割り当て
💾 メモリを意識した構築
📊 CPUクォータ管理
🧹 自動クリーンアップ
📝 詳細なビルドログ
📊 ビルドの概要とステータス

環境設定 🔧

階層的な構成システムを実装しました。

ファイル構造 📁

.env.example - すべてのオプションを含むテンプレート
.env - 設定（.env.example からコピー）
環境のオーバーライド:
- .env.dev - 開発設定
- .env.prod - 本番環境設定
- .env.test - テスト設定

読み込み優先度 ⚡

ファイルは次の順序で読み込まれます:

.env (基本設定)
環境固有のファイル:
- NODE_ENV=development → .env.dev
- NODE_ENV=production → .env.prod
- NODE_ENV=test → .env.test

後のファイルが前のファイルを上書きします。

開発💻

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run with hot reload
bun --hot run dev

# Build for production
bun build ./src/index.ts --target=bun

# Run production build
bun run start

パフォーマンス比較 📊

手術	パン	Node.js
依存関係をインストールする	約2秒	約15秒
コールドスタート	300ミリ秒	1000ミリ秒
ビルド時間	150ミリ秒	4000ミリ秒
メモリ使用量	約150MB	約400MB

ドキュメント 📚

コアドキュメント

高度な機能

自然言語処理- AIを活用した自動化分析と制御
カスタムプロンプトガイド- AIの動作を作成およびカスタマイズする
追加機能とツール- 追加のユーティリティと高度な機能

クライアント統合 🔗

カーソル統合 🖱️

.cursor/config/config.jsonに追加:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

クロードデスクトップ💬

Claude の設定に追加:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

コマンドライン💻

Windows ユーザーは提供されているスクリプトを使用できます:

scriptsディレクトリへ移動
start_mcp.cmdを実行します。

追加機能

音声機能 🎤

MCP サーバーはオプションで音声処理機能をサポートします。

🗣️ ウェイクワード検出（「ヘイジャービス」、「OK グーグル」、「アレクサ」）
🎯 高速ウィスパーを使用した音声テキスト変換
🌍 複数言語サポート
🚀 GPUアクセラレーションのサポート

音声機能の設定

前提条件

🐳 Docker がインストールされ、実行されている
🎮 CUDA 対応 NVIDIA GPU (オプション)
💾 4GB以上のRAM（8GB以上を推奨）

構成

.envで音声を有効にする:

ENABLE_SPEECH_FEATURES=true
ENABLE_WAKE_WORD=true
ENABLE_SPEECH_TO_TEXT=true
WHISPER_MODEL_PATH=/models
WHISPER_MODEL_TYPE=base

STT エンジンを選択してください:

# For standard Whisper
STT_ENGINE=whisper

# For Fast Whisper (GPU recommended)
STT_ENGINE=fast-whisper
CUDA_VISIBLE_DEVICES=0  # Set GPU device

利用可能なモデル 🤖

ニーズに応じて選択してください:

tiny.en : 最速、基本精度
base.en : バランスが良い（推奨）
small.en : 精度は高いが、速度は遅い
medium.en : 高精度、リソース集約型
large-v2 : 最高の精度、非常に多くのリソースを消費する

音声機能で起動

# Build with speech support
./docker-build.sh --speech

# Launch with speech features:
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

追加ツール 🛠️

Home Assistant エクスペリエンスを強化するために、 extra/ディレクトリにいくつかの強力なツールを追加しました。

Home Assistant Analyzer CLI ( ha-analyzer-cli.ts )
- AIモデルを使用したディープオートメーション分析
- セキュリティ脆弱性スキャン
- パフォーマンス最適化の提案
- システム健全性指標
音声テキスト変換の例( speech-to-text-example.ts )
- ウェイクワード検出
- 音声テキスト変換
- 複数言語サポート
- GPUアクセラレーションサポート
Claude デスクトップセットアップ( claude-desktop-macos-setup.sh )
- macOS 向け Claude Desktop の自動インストール
- 環境設定
- MCP統合設定

詳細な使用方法と例については、 Extras ドキュメントを参照してください。

ライセンス📄

MITライセンス。詳細はライセンスを参照してください。

著者👨‍💻

jango-blockchainedによって作成

標準 I/O トランスポートで実行 📝

MCP サーバーは、Claude などの AI アシスタントと直接統合するための JSON-RPC 2.0 stdio トランスポートモードをサポートしています。

MCP Stdio の機能

✅ JSON-RPC 2.0 互換性: MCP プロトコル標準を完全にサポート
✅ NPX サポート: npx homeassistant-mcpを使用してインストールせずに直接実行します
✅自動構成: 必要なディレクトリとデフォルト構成を作成します
✅クロスプラットフォーム: macOS、Linux、Windowsで動作します
✅ Claude デスクトップ統合: Claude デスクトップですぐに使用可能
✅パラメータ検証：ツールパラメータの自動検証
✅エラー処理: 標準化されたエラーコードと処理
✅詳細なログ記録: stdio を汚染せずにファイルにログを記録します

オプション1: NPXを使用する（最も簡単）

npx を使用して、インストールせずに MCP サーバーを直接実行します。

# Basic usage
npx homeassistant-mcp

# Or with environment variables
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

これにより、次のようになります。

パッケージを一時的にインストールする
JSON-RPC 2.0トランスポートを使用してstdioモードで自動的に実行します
ログ用のログディレクトリを作成する
存在しない場合はデフォルトの.envファイルを作成する

Claude Desktop またはその他の MCP クライアントとの統合に最適です。

Claude Desktopとの統合

Claude Desktop で MCP を使用するには:

Claudeデスクトップの設定を開く
「詳細設定」タブに移動します
「MCPサーバー」の下で「カスタム」を選択します
コマンドを入力してください: npx homeassistant-mcp
「保存」をクリック

Claude は Home Assistant の統合に MCP サーバーを使用するようになり、Claude から直接スマートホームを制御できるようになります。

オプション2: ローカルインストール

.envファイルを更新して、stdio トランスポートを有効にします。
USE_STDIO_TRANSPORT=true
stdio-start スクリプトを使用してサーバーを実行します。
./stdio-start.sh
利用可能なオプション:
./stdio-start.sh --debug # Enable debug mode ./stdio-start.sh --rebuild # Force rebuild ./stdio-start.sh --help # Show help

stdio モードで実行している場合:

サーバーはJSON-RPC 2.0形式を使用してstdin/stdout経由で通信します。
HTTPサーバーが起動されていません
stdioストリームの汚染を避けるため、コンソールログは無効になっています。
すべてのログはlogs/ディレクトリ内のログファイルに書き込まれます。

JSON-RPC 2.0 メッセージ形式

リクエスト形式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

応答フォーマット

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // Tool-specific result data
  }
}

エラー応答形式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {} // Optional error details
  }
}

通知形式（サーバーからクライアントへ）

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // Notification data
  }
}

サポートされているエラーコード

コード	説明	意味
-32700	解析エラー	無効なJSONを受信しました
-32600	無効なリクエスト	JSONは有効なリクエストオブジェクトではありません
-32601	メソッドが見つかりません	メソッドが存在しないか利用できません
-32602	無効なパラメータ	無効なメソッドパラメータ
-32603	内部エラー	内部JSON-RPCエラー
-32000	ツールの実行	ツールの実行中にエラーが発生しました
-32001	検証エラー	パラメータ検証に失敗しました

Claude Desktopとの統合

この MCP サーバーを Claude Desktop で使用するには:

Claude Desktop 構成を作成または編集します。
# On macOS nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Linux nano ~/.config/Claude/claude_desktop_config.json # On Windows notepad %APPDATA%\Claude\claude_desktop_config.json
MCP サーバー構成を追加します。
{ "mcpServers": { "homeassistant-mcp": { "command": "npx", "args": ["homeassistant-mcp"], "env": { "HASS_TOKEN": "your_home_assistant_token_here", "HASS_HOST": "http://your_home_assistant_host:8123" } } } }
Claude Desktop を再起動します。
Claude では、Home Assistant MCP ツールを使用できるようになりました。

JSON-RPC 2.0 メッセージ形式

使用法

NPXの使用（最も簡単）

Home Assistant MCP サーバーを使用する最も簡単な方法は、NPX を使用することです。

# Start the server in stdio mode
npx homeassistant-mcp

これにより、次の処理が自動的に実行されます。

stdioモードでサーバーを起動する
JSON-RPCメッセージを標準出力に出力する
ログメッセージをstderrに送信する
ログディレクトリが存在しない場合は作成する

stderr をリダイレクトしてログを非表示にし、JSON-RPC 出力のみを表示できます。

npx homeassistant-mcp 2>/dev/null

手動インストール

パッケージをグローバルまたはローカルにインストールする場合:

# Install globally
npm install -g homeassistant-mcp

# Then run
homeassistant-mcp

またはローカルにインストールします:

# Install locally
npm install homeassistant-mcp

# Then run using npx
npx homeassistant-mcp

Integrations

ホームアシスタントモデルコンテキストプロトコル（MCP）

概要

特徴

はじめる

前提条件

インストール

サーバーの実行

構成

建築

ツール

API

AIモデルとの統合

クロード・インテグレーション

カーソル統合

カーソル統合のトラブルシューティング

ライセンス

貢献

Home Assistant 用の MCP サーバー 🏠🤖

概要🌐

コア機能 ✨

なぜバン？🚀

前提条件 📋

クイックスタート 🚀

Docker ビルドオプション 🐳

1. 標準ビルド

2. 音声対応ビルド

3. GPUアクセラレーションビルド

ビルド機能

環境設定 🔧

ファイル構造 📁

読み込み優先度 ⚡

開発💻

パフォーマンス比較 📊

ドキュメント 📚

コアドキュメント

高度な機能

クライアント統合 🔗

カーソル統合 🖱️

クロードデスクトップ💬

コマンドライン💻

追加機能

音声機能 🎤

音声機能の設定

前提条件

構成

利用可能なモデル 🤖

音声機能で起動

追加ツール 🛠️

ライセンス📄

著者👨‍💻

標準 I/O トランスポートで実行 📝

MCP Stdio の機能

オプション1: NPXを使用する（最も簡単）

Claude Desktopとの統合

オプション2: ローカルインストール

JSON-RPC 2.0 メッセージ形式

リクエスト形式

応答フォーマット

エラー応答形式

通知形式（サーバーからクライアントへ）

サポートされているエラーコード

Claude Desktopとの統合

JSON-RPC 2.0 メッセージ形式

使用法

NPXの使用（最も簡単）

手動インストール

高度な使用法

Appeared in Searches