← 返回目录

Home Assistant MCP

社区

让你的 AI 助手指挥你的家 —— 50+ 工具、三种传输方式、一条 bunx 命令。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 其他第 88 / 230
Stars: ★ 57 热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Node.js 18+ · Bun · Docker
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 3 个月前
工具数: 82

58FMRS · C

该项目提供丰富的功能，社区活跃，但需要用户具备一定的 Home Assistant 知识。总体评价积极，但需注意权限和安全配置。

最强项 · 文档质量 14/20 最弱项 · 可靠性 8/20

可靠性

8/20

安全与权限

14/20

维护活跃度

12/20

文档质量

14/20

安装易用性

10/20

查看各项评分依据

可靠性 8/20: 证据显示有多个构建入口（dist/index.cjs, stdio-server.mjs, http-server.mjs），并存在CI工作流和测试套件（如README所述，但未提供具体细节）。由于未执行验证，得分不超过12。扣除点：未直接提供测试覆盖率的证据，且错误处理和边界情况的稳健性无法确认。
安全与权限 14/20: 未发现明显红线问题；环境变量用于令牌，文档建议使用长期令牌。但未确认是否实现了最小权限或危险操作的确认机制，且JWT认证仅用于HTTP/WS，未覆盖所有传输。扣除点：凭据处理细节和权限范围不透明。
维护活跃度 12/20: 仓库活跃，有近期提交和发布（Docker标签显示1.7.3），但未提供具体提交频率或问题响应时间。有Apache-2.0许可证。扣除点：维护治理和依赖更新信息不明确。
文档质量 14/20: README提供了详细的安装、配置和工具列表，并链接到完整文档。但缺少故障排除和限制说明。扣除点：未提供可验证的文档质量证据，且缺少针对常见问题的指南。
安装易用性 10/20: 提供了多种安装方法（bunx, npx, Docker, 源码），并包含客户端配置示例。但依赖Bun运行时，可能增加复杂度；且未提供明确的执行验证。扣除点：安装步骤虽多，但未验证在主流客户端中的实际可用性。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络

适合谁

希望将 AI 助手与智能家居深度集成的用户
需要语音控制且注重隐私（本地处理）的用户
需要多种部署方式（STDIO、HTTP、Docker）的开发者
希望探索 AI 驱动的智能家居自动化的开发者

不适合谁

没有 Home Assistant 实例的用户
需要官方支持的企业级用户（该项目为社区维护）
对隐私极为敏感且不希望任何远程托管的用户（但语音本地处理可缓解）
希望使用 MCP 服务器但仅需要基础功能的用户（其他简单服务器可能更合适）

所需权限

读取 Home Assistant 实体状态（灯光、气候、媒体等）
控制设备状态（开/关、亮度、温度等）
访问历史数据、日志和配置
执行自动化、场景和通知
管理仪表盘和待办事项

风险与副作用

令牌泄露：长期访问令牌可能被滥用，导致未经授权的控制。
配置错误可能导致对设备进行意外操作（例如关闭关键安全设备）。
HTTP/WS 传输需要 JWT 认证，但若配置不当，可能暴露服务。
语音功能可能引入额外的安全风险（如麦克风权限）。

安装接入

准备工作

运行环境：Node.js 18+ · Bun · Docker

HASS_HOST 必填你的 Home Assistant 实例地址（如 http://homeassistant.local:8123），必填。

HASS_TOKEN 必填密钥 Home Assistant 的长期访问令牌，在 HA 用户资料页（安全设置）中创建，必填且为敏感凭据。

JWT_SECRET 可选密钥 HTTP/WS 传输的 JWT 认证密钥（至少 32 字符），敏感凭据，可选。

其他可选配置项（2 个）

PORT 可选 HTTP 服务器端口（默认 4000），仅 HTTP 传输需要，可选。

LOG_LEVEL 可选日志级别（debug | info | warn | error），可选。

确保你有 Home Assistant 实例和长期访问令牌（在用户配置文件页创建）。
在 Claude Desktop 的配置文件 claude_desktop_config.json 中添加 mcpServers 配置，填入命令 bunx 和参数。
设置环境变量 HASS_HOST 和 HASS_TOKEN。
重启 Claude Desktop。
或者，使用 Smithery 一键安装：npx @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude。

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 Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "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"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add homeassistant-mcp -e HASS_HOST=http://your-ha-instance:8123 -e HASS_TOKEN=your_long_lived_access_token -- bunx github:jango-blockchained/advanced-homeassistant-mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在 claude_desktop_config. 中加入 bunx 配置并重启 Claude，客户端工具列表中应出现 lights、climate、locks 等 50+ 个工具；然后问"现在客厅的温度是多少？"，能返回真实实体状态即说明连接成功。

常见排障

1. 检查环境变量 HASS_HOST 和 HASS_TOKEN 是否正确设置。
2. 确保 Home Assistant 实例可从运行 MCP 服务器的机器访问（网络、端口）。
3. 检查令牌是否有效且未过期。
4. 查看日志：设置 LOG_LEVEL=debug 以获得详细输出。
5. 对于 HTTP/WS 传输，检查 JWT_SECRET 是否设置并至少 32 字符。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

把卧室的所有灯都关掉
把恒温器设到 72°F
锁上所有的门并启动扫地机器人
显示我这周的能耗情况

工具能力 82

lights list 只读

列出所有灯光实体及状态。

lights get 只读

获取单个灯光的详细信息。

lights turn on/off 写入

打开或关闭指定灯光。

lights brightness 写入

设置灯光亮度。

lights color temp 写入

设置色温。

lights RGB 写入

设置 RGB 颜色。

lights effects 写入

设置灯光效果。

climate list 只读

列出所有气候实体。

展开其余 74 个工具

climate get 只读

获取气候实体状态。

climate HVAC modes 写入

设置 HVAC 模式（加热、制冷等）。

climate target temp 写入

设置目标温度。

climate fan mode 写入

设置风扇模式。

climate humidify 写入

控制湿度。

media list 只读

列出媒体播放器。

media get 只读

获取媒体播放器状态。

media play/pause 写入

播放或暂停。

media volume 写入

设置音量。

media source 写入

选择输入源。

media sound mode 写入

设置音效模式。

media shuffle 写入

切换随机播放。

covers list 只读

列出所有覆盖物（窗帘、卷帘等）。

covers get 只读

获取覆盖物状态。

covers open/close 写入

打开或关闭。

covers position 写入

设置位置百分比。

covers tilt 写入

调整倾斜角度。

covers garage door 写入

控制车库门。

locks list 只读

列出所有门锁。

locks get 只读

获取门锁状态。

locks lock/unlock 写入

锁定或解锁。

fans list 只读

列出所有风扇。

fans get 只读

获取风扇状态。

fans speed 写入

设置风扇速度。

fans oscillation 写入

控制摇头。

fans direction 写入

设置风向。

fans preset 写入

选择预设模式。

vacuums list 只读

列出所有扫地机器人。

vacuums get 只读

获取扫地机器人状态。

vacuums start/stop/dock 写入

启动、停止或返回底座。

vacuums spot clean 写入

定点清洁。

vacuums fan speed 写入

设置吸力。

alarm list 只读

列出所有报警面板。

alarm get 只读

获取报警状态。

alarm arm home/away/night 写入

布防（在家/外出/夜间）。

alarm disarm 写入

撤防。

switches list 只读

列出所有开关。

switches get 只读

获取开关状态。

switches turn on/off/toggle 写入

打开、关闭或切换。

scenes list 只读

列出所有场景。

scenes activate 写入

激活指定场景。

automations list 只读

列出所有自动化。

automations toggle 写入

启用或禁用自动化。

automations trigger 写入

手动触发自动化。

automations create/edit/delete 破坏性

创建、编辑或删除自动化。

notifications push 写入

通过 Home Assistant 推送通知。

history query 只读

查询历史状态。

add-ons install 写入

安装 Home Assistant 附加组件。

add-ons configure 写入

配置附加组件。

add-ons control 写入

控制附加组件（启动、停止等）。

packages HACS 写入

管理 HACS 集成。

maintenance orphaned devices 只读

查找孤立设备。

maintenance battery warnings 只读

获取低电量警告。

maintenance energy analysis 只读

分析能源消耗。

smart scenarios nobody-home 写入

检测无人模式。

smart scenarios window/heat conflicts 写入

检测窗户和暖气冲突。

smart scenarios energy waste 写入

检测能源浪费。

lighting animations 写入

设置灯光动画。

lighting scenarios 写入

设置灯光场景。

lighting showcase 写入

灯光展示。

lighting BPM/beat detection 写入

根据节拍检测切换灯光。

voice wake word detection 只读

唤醒词检测。

voice speech-to-text 只读

语音转文字。

voice commands 写入

执行语音命令。

dashboard query 只读

查询 Lovelace 仪表盘。

dashboard manage 写入

管理仪表盘。

templates render Jinja2 只读

通过 Home Assistant 渲染 Jinja2 模板。

to-do lists add 写入

添加待办事项。

to-do lists update 写入

更新待办事项。

to-do lists remove 破坏性

删除待办事项。

traces automation/script 只读

获取自动化或脚本的执行痕迹。

search full-text entity 只读

全文搜索实体。

entity state get 只读

获取任意实体的当前状态。

error log query 只读

查询 Home Assistant 错误日志。

使用场景

通过自然语言控制 Home Assistant 设备："关闭卧室所有灯"。

设置恒温器温度："将恒温器设置为 72°F"。

锁定门并启动扫地机器人："锁好所有门并开始打扫"。

查询能源消耗："显示本周能源消耗"。

执行场景："激活电影场景"。

健康检查和维护："检查 Home Assistant 健康状况"。

支持客户端

Claude Desktop

Cursor

依据项目文档列出，未经本站实测。

详细介绍

Home Assistant MCP 服务器将 AI 助手（如 Claude、GPT、Cursor、Copilot）通过模型上下文协议连接到 Home Assistant。提供 50 多个工具，涵盖灯光、气候、媒体、锁、窗帘、风扇、吸尘器、报警、场景、自动化、通知、历史、能源监控、维护等。支持 STDIO 和 HTTP+WS 传输，并可通过 Docker 或 bunx 快速部署。带有语音控制功能（唤醒词检测、语音转文字）。