Home Assistant Model Context Protocol (MCP)

🏠 Home Assistant MCP

家に話しかけましょう。 AI アシスタント（Claude、GPT、Cursor、Copilot）を、Model Context Protocol 経由で Home Assistant に接続します。50 以上のツール、3 種類のトランスポート、bunx コマンド 1 つ。

# ⚡ Fastest way to try it
bunx github:jango-blockchained/advanced-homeassistant-mcp

🚀 クイックスタート

Home Assistant のインスタンスと長期アクセストークン（こちらから作成）が必要です。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

Claude を再起動します。 これで完了です。照明をつけるよう頼んでみましょう。

Cursor / VS Code

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

{
  "mcp.servers": {
    "homeassistant-mcp": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "dist/stdio-server.mjs"],
      "env": {
        "HASS_HOST": "${env:HASS_HOST}",
        "HASS_TOKEN": "${env:HASS_TOKEN}"
      }
    }
  }
}

Smithery（ワンクリック）

Smithery レジストリから直接インストールできます。設定ファイルは不要です。

npx @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude

📦 インストール方法一覧

利用可能な Docker タグ：

• latest - 最新の安定版リリース
• 1.7.3、1.7、1 - タグ付きバージョン
• dev - main ブランチからの最新開発ビルド

🎯 できること

接続すると、人に話しかけるように自宅に話しかけられます。

"Turn off all lights in the bedroom"
"Set the thermostat to 72°F"
"Lock all doors and start the vacuum"
"Show me energy consumption this week"
"What's the temperature in the living room?"
"Activate the movie scene"
"Notify everyone that dinner is ready"
"Check my Home Assistant health"
"Find orphaned devices with low battery"
"Analyze my light usage patterns"

すべてのコマンドは、50 種類以上のツールのいずれかに対応しています。照明、空調、メディア、ロック、カバー、ファン、掃除機、アラーム、シーン、自動化、通知、履歴、エネルギー監視、メンテナンスなどを操作できます。

🎙️ 音声機能（音声操作）

セットアップを、音声で完全に操作できるスマートホームアシスタントに変えられます。音声統合では、プライバシーに配慮したローカル音声処理を利用できます。

• ウェイクワード検出：wyoming-openwakeword を利用します（デフォルト：「Hey Jarvis」）。
• 音声テキスト変換：faster-whisper を使用した、高速なローカル文字起こしです。
• オーディオ統合：シームレスにマイクへアクセスできる PulseAudio の直接統合です。

音声機能を有効にするには、専用の Docker Compose ファイルを使用してください。

docker-compose -f docker-compose.speech.yml up -d

詳しい設定方法については、音声機能ガイドをご覧ください。

🧱 アーキテクチャ

┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  AI Assistant │◄───►│   Home Assistant    │◄───►│  Your Smart Home │
│ (Claude/GPT)  │     │    MCP Server       │     │  (Home Assistant)│
└──────────────┘     └─────────────────────┘     └──────────────────┘
                         │           │
                    ┌────┘           └────┐
                    ▼                     ▼
              ┌────────────┐      ┌──────────────┐
              │  HTTP/WS   │      │    STDIO     │
              │ (Express)  │      │ (fastmcp v3) │
              └────────────┘      └──────────────┘

3 種類のトランスポートを 1 つのコードベースで提供しています。環境に合ったものを選んでください。どれも同じ 50 個以上のツールを公開します。

• STDIO — Claude Desktop、Cursor、VS Code（ローカルエディターとの連携）向け
• HTTP+WS — JWT 認証、レート制限、WebSocket ストリーミングを備えた、リモート AI ホスト向け
• HTTP (fastmcp) — 独自のミドルウェアを使わない軽量な HTTP トランスポート

⚙️ 設定

最小限の設定で利用できます。必須の環境変数は 2 つです。

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=eyJ...                          # long-lived access token

任意の設定：

PORT=7123                                  # HTTP server port (default: 4000)
LOG_LEVEL=info                             # debug | info | warn | error
JWT_SECRET=...                             # for HTTP/WS auth (min 32 chars)

20 個以上ある環境変数の全リストについては、設定ドキュメントをご覧ください。

🛠️ 開発

bun install              # install dependencies
bun run build:all        # build all three entry points
bun test                 # run test suite (80% coverage threshold)
bun run lint             # ESLint + Prettier
bun run typecheck        # TypeScript type checking

Bun、TypeScript、fastmcp で構築されています。エントリーポイントは 3 つあります。

• dist/index.cjs — Express ベースのカスタム MCP サーバー上で動作する HTTP+WS
• dist/stdio-server.mjs — fastmcp v3 を介した STDIO
• dist/http-server.mjs — fastmcp v3 を介した HTTP

📖 ドキュメント

完全なドキュメントは jango-blockchained.github.io/advanced-homeassistant-mcp にあります。インストール、設定、50 個以上のツール、デプロイ（HTTP、STDIO、Smithery）、アーキテクチャの詳細解説、ガイドを掲載しています。

🤝 コントリビューション

プルリクエストを歓迎します。シンプルに進めましょう。同じコードスタイルを保ち、テストを追加し、公開 API に変更を加えた場合はドキュメントも更新してください。

1. フォークする
2. ブランチを作成する
3. コードを書く
4. テストする
5. プルリクエストを送る

詳細なガイドラインについては、CONTRIBUTING.mdをご覧ください。

📄 ライセンス

MIT — 何かクールなものを作りましょう。

スマートホームは MCP を話します。今度は AI も MCP を話します。 🏠⚡🤖🔋

電池は付属しています。🔋