Homeassistant MCP

🚀 家庭助理 Home Assistant 説明ドキュメント

このドキュメントでは、家庭助理 Home Assistant の設定方法や使用方法、エラー処理などについて詳しく説明します。

📦 設定ガイド

MCP サーバー設定

設定ファイル例

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_home_assistant_token_here",
        "HASS_HOST": "http://your_home_assistant_host:8123"
      }
    }
  }
}

環境変数

• HASS_TOKEN: Home Assistant のアクセストークンです。
• HASS_HOST: Home Assistant サービスの URL で、http://IP:ポート の形式で指定します。

起動スクリプト

方法 1: Node.js で直接実行

node index.js

方法 2: npm パッケージを使用

1. MCP サーバーをインストールします。

npm install homeassistant-mcp

2. サーバーを起動します。

npx homeassistant-mcp

Home Assistant の起動スクリプトを使用

以下の内容を homeassistant.conf ファイルに追加します。

[HomeAssistantMCP]
command=node
args=index.js
environment=HASS_TOKEN="your_token_here",HASS_HOST="http://IP:port"

その後、Home Assistant サービスを再起動します。

💻 標準入出力モード（_stdio）

標準入出力モードを有効にする

.env ファイルに以下の内容を追加します。

USE_STDIO_TRANSPORT=true

スクリプトを実行する

方法 1: Node.js で直接実行

node index.js --stdio

方法 2: npm パッケージを使用

npx homeassistant-mcp --stdio

オプションパラメータ

• --debug: デバッグモードを有効にします。
• --rebuild: プロジェクトを強制的に再構築します。
• --help: ヘルプ情報を表示します。

標準入出力メッセージ形式

リクエスト形式

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

レスポンス形式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // ツール固有の結果データ
  }
}

エラーレスポンス形式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32700,
    "message": "エラーメッセージ",
    "data": {} // オプションのエラー詳細
  }
}

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

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // 通知データ
  }
}

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

🔗 Claude Desktop との統合

設定手順

設定ファイルを変更する

以下のパスにある設定ファイルを見つけるか、作成します。

• macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Linux:

nano ~/.config/Claude/claude_desktop_config.json

• Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

MCP サーバー設定を追加する

ファイルに以下の内容を追加または変更します。

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_token_here",
        "HASS_HOST": "http://IP:port"
      }
    }
  }
}

サービスを再起動する

設定ファイルを保存した後、Claude Desktop サービスを再起動します。

💻 使い方の例

MCP サーバーを起動する

npx homeassistant-mcp --stdio

リクエストを送信する例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getWeather",
  "params": {
    "location": "北京"
  }
}

レスポンスを受信する例

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "temperature": 25,
    "condition": "晴朗"
  }
}

🛠️ エラー処理

一般的なエラーと解決策

• エラーコード -32700: リクエストの JSON 形式が無効です。リクエストデータが JSON 標準に準拠していることを確認してください。
• エラーコード -32601: メソッドが見つかりません。呼び出すメソッド名が正しく、登録されていることを確認してください。
• エラーコード -32000: ツールの実行に失敗しました。環境変数と依存関係が正しく設定されていることを確認してください。

⚙️ 高度な機能

ログ記録

デバッグモードを有効にして詳細なログを取得します。

npx homeassistant-mcp --debug stdio

ログファイルは通常、プロジェクトディレクトリの logs フォルダに保存され、具体的な場所はプロジェクトの設定によって異なります。

パフォーマンスチューニング

メモリ最適化

--max-old-space-size パラメータを使用して、V8 エンジンの最大メモリ使用量を制限します。

node --max-old-space-size=512 index.js --stdio

ネットワークパフォーマンス

プロキシサーバーを設定するか、HTTP リクエストのタイムアウト設定を調整します。

🔒 セキュリティに関する注意事項

• アクセス制御: MCP サーバーが信頼できるソースからの接続のみを許可するようにしてください。
• トークンのセキュリティ: HASS_TOKEN を保存および転送する際には、HTTPS などの安全なプロトコルを使用して、不正アクセスを防止してください。
• ログ監視: 定期的にログファイルを確認し、潜在的なセキュリティイベントを検出して処理してください。

📝 更新履歴

バージョン 1.0.0 (2023-10-05)

• 標準入出力モードのサポートを追加しました。
• エラー処理メカニズムを最適化しました。
• Claude Desktop との統合体験を改善しました。

バージョン 0.9.0 (2023-08-10)

• 初期バージョンがリリースされ、基本的な機能が提供されました。

📞 連絡先

フィードバックや技術サポートが必要な場合は、公式ドキュメント を参照するか、サポートチームにお問い合わせください。