Home Assistant Model Context Protocol (MCP)

🏠 Home Assistant MCP

和你的家对话。 你的 AI 助手（Claude、GPT、Cursor、Copilot）通过模型上下文协议连接到 Home Assistant。50 多种工具、三种传输方式，只需一条 bunx 命令。

# ⚡ 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) │
              └────────────┘      └──────────────┘

三种传输方式，一套代码库。选择适合你设置的方式——它们都提供相同的 50 多种工具。

• STDIO — 适用于 Claude Desktop、Cursor、VS Code（本地编辑器集成）
• HTTP+WS — 适用于远程 AI 主机，支持 JWT 身份验证、速率限制和 WebSocket 流式传输
• HTTP (fastmcp) — 轻量级 HTTP 传输，无需定制中间件

⚙️ 配置

配置极简。需要设置两个变量：

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 构建。提供三个入口点：

• 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）、架构深入解析和指南。

🤝 贡献

欢迎提交 PR。保持简洁——遵循相同的代码风格、添加测试，如果修改了公共 API，请更新文档。

1. Fork 项目
2. 创建分支
3. 编写代码
4. 运行测试
5. 提交 PR

完整指南请参阅 CONTRIBUTING.md。

📄 许可证

MIT —— 去构建点酷东西吧。

你的智能家居会说 MCP 了。现在你的 AI 也会说了。 🏠⚡🤖🔋

电池已包含。🔋