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

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

概要

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

• Home Assistantデバイスでコマンドを実行する

• スマートホームに関する情報を取得する

• 長時間実行操作のストリーム応答

• パラメータと入力を検証する

• 一貫したエラー処理を提供する

Related MCP server: SwitchBot MCP Server

特徴

• モジュラーアーキテクチャ- トランスポート、ミドルウェア、ツール間の明確な分離

• 型付きインターフェース- 開発者エクスペリエンスを向上させるために完全に 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 サーバーは階層型アーキテクチャで構築されています。

1. トランスポート層- 通信プロトコル（stdio、HTTP）を処理します

2. ミドルウェア層- パイプラインを通じてリクエストを処理する

3. ツールレイヤー- 特定の機能を実装する

4. リソース層- ステートフルリソースを管理する

ツール

ツールは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"
      }
    }
  }
}

この構成:

1. stdioトランスポートでMCPサーバーを実行します

2. すべてのstderr出力を/dev/nullにリダイレクトします

3. grepを使用して{"jsonrpc":"2.0"を含む行をstdoutでフィルタリングし、クリーンなJSON-RPC出力を確保します。

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

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

1. カーソル設定で正しいコマンドと引数を使用していることを確認してください

   • bashスクリプトのアプローチは、有効なJSON-RPCメッセージのみがカーソルに到達することを保証する。

   • 接続する前に、 bun run buildを実行してサーバーが構築されていることを確認してください。

2. サーバーが JSON-RPC メッセージを標準出力に適切に出力していることを確認します。

   bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt

   次に、json_only.txt を調べて、有効な JSON-RPC メッセージのみが含まれていることを確認します。

3. grep がシステムにインストールされていることを確認してください (ほとんどのシステムではデフォルトで利用できるはずです)

4. 次のコマンドでサーバーを再構築してみてください。

   bun run build

5. 環境変数でDEBUG_STDIO=true設定してデバッグモードを有効にします。

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

1. カーソルの再起動

2. カーソルのキャッシュをクリアする (ヘルプ > 開発者 > キャッシュをクリアして再読み込み)

3. 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（オプション、音声処理を高速化）

クイックスタート 🚀

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

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

2. 環境を設定します。

# 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

3. 設定を構成します。

• Home Assistantの詳細を.envファイルで編集する

• 必須: HASS_TOKEN (長期アクセストークン) を追加します

4. 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クォータ管理

• 🧹 自動クリーンアップ

• 📝 詳細なビルドログ

• 📊 ビルドの概要とステータス

環境設定 🔧

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

ファイル構造 📁

1. .env.example - すべてのオプションを含むテンプレート

2. .env - 設定（.env.example からコピー）

3. 環境のオーバーライド:

   • .env.dev - 開発設定

   • .env.prod - 本番環境設定

   • .env.test - テスト設定

読み込み優先度 ⚡

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

1. .env (基本設定)

2. 環境固有のファイル:

   • 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

パフォーマンス比較 📊

ドキュメント 📚

コアドキュメント

• 設定ガイド

• APIドキュメント

• トラブルシューティング

高度な機能

• 自然言語処理- 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 ユーザーは提供されているスクリプトを使用できます:

1. scriptsディレクトリへ移動

2. start_mcp.cmdを実行します。

追加機能

音声機能 🎤

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

• 🗣️ ウェイクワード検出（「ヘイ ジャービス」、「OK グーグル」、「アレクサ」）

• 🎯 高速ウィスパーを使用した音声テキスト変換

• 🌍 複数言語サポート

• 🚀 GPUアクセラレーションのサポート

音声機能の設定

前提条件

1. 🐳 Docker がインストールされ、実行されている

2. 🎮 CUDA 対応 NVIDIA GPU (オプション)

3. 💾 4GB以上のRAM（8GB以上を推奨）

構成

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

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

2. 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/ディレクトリにいくつかの強力なツールを追加しました。

1. Home Assistant Analyzer CLI ( ha-analyzer-cli.ts )

   • AIモデルを使用したディープオートメーション分析

   • セキュリティ脆弱性スキャン

   • パフォーマンス最適化の提案

   • システム健全性指標

2. 音声テキスト変換の例( speech-to-text-example.ts )

   • ウェイクワード検出

   • 音声テキスト変換

   • 複数言語サポート

   • GPUアクセラレーションサポート

3. 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

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

1. パッケージを一時的にインストールする

2. JSON-RPC 2.0トランスポートを使用してstdioモードで自動的に実行します

3. ログ用のログディレクトリを作成する

4. 存在しない場合はデフォルトの.envファイルを作成する

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

Claude Desktopとの統合

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

1. Claudeデスクトップの設定を開く

2. 「詳細設定」タブに移動します

3. 「MCPサーバー」の下で「カスタム」を選択します

4. コマンドを入力してください: npx homeassistant-mcp

5. 「保存」をクリック

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

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

1. .envファイルを更新して、stdio トランスポートを有効にします。

   USE_STDIO_TRANSPORT=true

2. 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
  }
}

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

Claude Desktopとの統合

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

1. 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

2. 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"
         }
       }
     }
   }

3. Claude Desktop を再起動します。

4. Claude では、Home Assistant MCP ツールを使用できるようになりました。

JSON-RPC 2.0 メッセージ形式

使用法

NPXの使用（最も簡単）

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

# Start the server in stdio mode
npx homeassistant-mcp

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

1. stdioモードでサーバーを起動する

2. JSON-RPCメッセージを標準出力に出力する

3. ログメッセージをstderrに送信する

4. ログディレクトリが存在しない場合は作成する

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

高度な使用法