Enhanced Homeassistant MCP

🚀 拡張 Home Assistant MCP

包括的なMCP（Model Context Protocol）サーバーで、Home Assistantとの広範な統合を提供し、AIアシスタントがスマートホームデバイス、自動化、およびシステム管理と対話できるようにします。

🚀 クイックスタート

NPXを使用したクイックスタート

インストール不要！ npxで直接実行します：

# Home Assistantの資格情報を設定
export HOMEASSISTANT_URL="http://your-ha-ip:8123"
export HOMEASSISTANT_TOKEN="your-long-lived-access-token"

# サーバーを起動
npx @thelord/enhanced-homeassistant-mcp

📖 NPXの完全な使用ガイド →

🚧 Smitheryデプロイメントの状態: 現在、Smitheryのツールスキャン中のタイムアウトを防ぐためにツールの読み込みを最適化しています。詳細はTIMEOUT_RESOLUTION.mdを参照してください。

前提条件

• Node.js 18+
• APIアクセス可能なHome Assistantインスタンス
• Home Assistantの長期アクセストークン

インストール

# リポジトリをクローン
git clone https://github.com/gilberth/enhanced-homeassistant-mcp.git
cd enhanced-homeassistant-mcp

# 依存関係をインストール
npm install

# 環境テンプレートをコピー
cp .env.example .env

設定

.envファイルを編集して、Home Assistantの詳細を入力します：

HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your_long_lived_access_token_here
DEBUG=false
REQUEST_TIMEOUT=10000

アクセストークンの取得方法

1. ブラウザでHome Assistantを開きます。
2. プロファイルに移動します（サイドバーのユーザー名をクリック）。
3. 「Long-Lived Access Tokens」までスクロールします。
4. 「Create Token」をクリックします。
5. 名前を付けて、生成されたトークンをコピーします。

サーバーの実行

オプション1: NPX（推奨 - インストール不要）

# クイックスタート
npx @thelord/enhanced-homeassistant-mcp

# オプション付き
npx @thelord/enhanced-homeassistant-mcp --debug start
npx @thelord/enhanced-homeassistant-mcp inspect
npx @thelord/enhanced-homeassistant-mcp health

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

# 開発モード
npm run dev

# 本番モード
npm run build
npm start

# MCPインスペクターを使用したテスト
npm run inspector

🐳 Dockerデプロイメント（推奨）

Dockerを使用した簡単で安全なデプロイメント方法：

# イメージをビルド
docker build -t enhanced-homeassistant-mcp .

# コンテナを実行
docker run -d \
  --name homeassistant-mcp \
  --restart unless-stopped \
  -e HOME_ASSISTANT_URL="http://your-hass-ip:8123" \
  -e HOME_ASSISTANT_TOKEN="your_long_lived_token" \
  enhanced-homeassistant-mcp

📖 Dockerの完全ガイド: 詳細な手順はDOCKER.mdを参照してください。

☁️ Smitheryデプロイメント（クラウド）

Smitheryを通じてクラウドでデプロイされたサーバーを使用するには：

1. アクセス: Smithery.ai
2. 検索: @gilberth/enhanced-homeassistant-mcp
3. インスタンスを設定:
   • Home Assistant URL
   • 長期アクセストークン
   • オプション（デバッグ、タイムアウト）

// Smithery SDKを使用する
import { createSmitheryUrl } from "@smithery/sdk";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const config = {
  homeAssistantToken: "your_token",
  homeAssistantUrl: "http://your-hass-ip:8123",
};

const serverUrl = createSmitheryUrl(
  "https://server.smithery.ai/@gilberth/enhanced-homeassistant-mcp",
  { config, apiKey: "your-smithery-api-key" }
);

🎯 Smitheryの利点: インフラストラクチャの設定不要、自動スケーリング、グローバルアクセス

✨ 主な機能

📊 基本操作

• ✅ APIステータスの検証
• 📱 エンティティ状態の管理
• 🔄 高度なパラメータを持つサービス呼び出し
• 📝 エンティティの検出と一覧表示
• 🛠️ 設定情報

🤖 自動化と制御

• 📜 自動化の管理（有効/無効/トリガー）
• 🎬 シーンのアクティブ化
• 📜 スクリプトの実行
• 🔘 入力ブール値の制御
• 📅 スケジュールされた自動化の洞察

📊 履歴と監視

• 📈 エンティティの履歴追跡
• 📝 ログブックのエントリー
• ⚠️ エラーログの監視
• 📡 システムイベント
• 🔍 設定の検証

🏠 デバイス制御

• 💡 照明: 明るさ、色、温度の制御
• 🌡️ 空調: 温度、HVACモード、プリセット
• 📺 メディアプレーヤー: 再生/一時停止、音量、メディア選択
• 🏠 カバー: 開閉、位置制御
• 📢 通知: 複数サービスのメッセージング
• 🔍 デバイス検出: タイプ/ドメインでフィルタリング

⚙️ システム管理

• 📊 システム情報とヘルスチェック
• 🏷️ テンプレートレンダリング（Jinja2）
• 🏠 エリアとデバイスの管理
• 🔌 統合の監視
• 🔄 システムの再起動機能
• 📱 スーパーバイザーとアドオンの管理
• 🔍 エンティティの検索と検出

🛠️ 利用可能なツール

基本ツール

自動化ツール

履歴ツール

デバイス制御ツール

システムツール

💻 使用例

基本的なエンティティ制御

// 照明の状態を取得
const lightState = await homeassistant_get_entity_state({
  entity_id: "light.living_room",
});

// 明るさと色を指定して照明をオンにする
const result = await homeassistant_control_lights({
  entity_id: "light.living_room",
  action: "turn_on",
  brightness_pct: 75,
  color_name: "warm_white",
});

自動化管理

// すべての自動化を一覧表示
const automations = await homeassistant_list_automations();

// 自動化を有効にする
const enabled = await homeassistant_toggle_automation({
  entity_id: "automation.morning_routine",
  action: "turn_on",
});

// シーンをアクティブ化する
const scene = await homeassistant_activate_scene({
  entity_id: "scene.movie_time",
});

空調制御

// サーモスタットの温度を設定
const climate = await homeassistant_control_climate({
  entity_id: "climate.living_room",
  temperature: 22,
  hvac_mode: "heat",
});

システム情報

// システムの概要を取得
const systemInfo = await homeassistant_system_info();

// エンティティを検索
const searchResults = await homeassistant_search_entities({
  search: "temperature",
  domain: "sensor",
});

🎮 クライアントの使用例

使用可能なクライアントの例はディレクトリにあります：

📁 利用可能な例

• simple-client.js - 基本的な接続とツールの使用
• smithery-client.js - 全機能のデモンストレーション
• secure-client.js - 環境ベースの安全な設定

🚀 例を使ったクイックスタート

cd examples
npm install
cp .env.example .env
# .envを自分の資格情報で編集
npm run secure

🔗 Smitheryとの連携: これらの例はSmithery.aiでデプロイされたサーバーと連携できます。

📖 詳細ガイド: 完全なセットアップ手順はを参照してください。

🔧 開発

プロジェクト構造

src/
├── index.ts                    # メインサーバーファイル
├── utils/
│   └── api.ts                  # APIユーティリティ
└── tools/
    └── homeassistant/
        ├── basic.ts            # 基本的なHA操作
        ├── automation.ts       # 自動化ツール
        ├── history.ts          # 履歴と監視
        ├── devices.ts          # デバイス制御
        └── system.ts           # システム管理

新しいツールの追加方法

1. 適切なツールファイルに新しい関数を作成します。
2. server.tool()を使用してサーバーに登録します。
3. 既存のエラーハンドリングとレスポンスフォーマットのパターンに従います。
4. READMEにドキュメントを追加します。

テスト

# インタラクティブなテストのためにインスペクターで実行
npm run inspector

# 特定のエンドポイントをテスト
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8123/api/states"

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

一般的な問題

接続失敗

• HOME_ASSISTANT_URLが正しく、アクセス可能であることを確認します。
• Home Assistantが実行中であることを確認します。
• ファイアウォールが接続をブロックしていないことを確認します。

認証失敗

• 長期アクセストークンが正しいことを確認します。
• トークンが期限切れまたは取り消されていないことを確認します。
• トークンに必要な権限があることを確認します。

エンティティが見つからない

• homeassistant_list_all_entitiesを使用して正しいエンティティIDを見つけます。
• エンティティが存在し、Home Assistantで有効になっていることを確認します。
• 正しいドメインプレフィックス（例：light., sensor.）を確認します。

サービス呼び出し失敗

• homeassistant_list_servicesを使用してサービスの可用性を確認します。
• サービスのパラメータがデバイスに適していることを確認します。
• 一部のサービスは特定のエンティティタイプまたは状態を必要とします。

デバッグモード

.envでデバッグログを有効にします：

DEBUG=true

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを開きます。

開発ガイドライン

• 既存のコードスタイルとパターンに従います。
• 適切なTypeScript型を追加します。
• すべてのAPI呼び出しにエラーハンドリングを含めます。
• 新機能のドキュメントを更新します。
• 実際のHome Assistantインスタンスでテストします。

📜 APIリファレンス

このMCPサーバーはHome Assistant REST APIを使用しています。主要なエンドポイント：

• /api/ - API情報
• /api/states - エンティティの状態
• /api/services - 利用可能なサービス
• /api/config - 設定
• /api/history - 履歴データ
• /api/logbook - ログブックのエントリー

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細はLICENSEファイルを参照してください。

🙏 謝辞

• Home Assistant - 素晴らしいスマートホームプラットフォーム
• Model Context Protocol - プロトコル仕様
• TypeScript - 言語とツール

📞 サポート

問題が発生した場合や質問がある場合は：

1. トラブルシューティングセクションを確認します。
2. 既存のGitHubイシューを検索します。
3. 新しいイシューを作成し、以下の情報を含めます：
   • Home Assistantのバージョン
   • MCPサーバーのログ
   • 再現手順
   • 期待される動作と実際の動作

❤️ Home Assistantコミュニティのために作られました