Home Assistant MCP Server

什么是 Home Assistant MCP Server？

这个 Home Assistant MCP 服务器是由 tevonsb 开发的社区 Node.js 服务器，让 LLM 可以访问你本地的 Home Assistant 实例：控制和监测设备，管理自动化、加载项和 HACS 包，并接收实时更新。

它用 TypeScript 编写，通过长期访问令牌连接 Home Assistant，可从源码运行，也可在 Docker 中运行。它不是官方集成：Home Assistant 现已内置官方的 Model Context Protocol Server 集成，对比见下文。

如何使用 Home Assistant MCP Server？

前置条件：

• Node.js 20.10.0 或更高版本，以及 npm
• 正在运行的 Home Assistant 实例和长期访问令牌
• 可选：Docker Compose、HACS（用于包管理）以及 Supervisor 访问权限（用于加载项管理）

从源码安装：

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp
npm install
npm run build

配置 .env 文件（复制 .env.example）：

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
PORT=3000
NODE_ENV=production
DEBUG=false

Claude Desktop

让 Claude Desktop 指向构建出的 dist 入口，并传入相同的变量。README 指出，这种方式会在 Claude 内运行 MCP 服务器，不使用 Docker 部署。

{
  "mcpServers": {
    "homeassistant": {
      "command": "node",
      "args": ["/path/to/homeassistant-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "HASS_HOST": "http://homeassistant.local:8123",
        "HASS_TOKEN": "your_home_assistant_token",
        "HASS_SOCKET_URL": "ws://homeassistant.local:8123/api/websocket",
        "PORT": "3000",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Cursor 和 VS Code

README 未涉及这两个客户端。作为 stdio 服务器，可以把同样的 node /path/to/homeassistant-mcp/dist/index.js 命令和 env 值添加到 .cursor/mcp.json 或 .vscode/mcp.json。

Docker

README 推荐使用 Docker Compose 运行 HTTP 服务器：

cp .env.example .env
docker compose up -d

服务器监听 http://localhost:3000，健康检查地址为 /health。

Home Assistant MCP Server 的主要功能

• 设备控制：灯光（亮度、色温、RGB）、空调、窗帘、开关、风扇、门锁、扫地机器人、媒体播放器和摄像头。
• 状态监测与查询，支持按区域和楼层分组，可访问历史数据。
• 通过 Server-Sent Events（SSE）获取实时更新，可按域或实体筛选。
• 自动化管理：创建、编辑、复制、启用或禁用，以及手动触发带复杂触发器和条件的自动化。
• 通过 Supervisor 管理加载项：浏览、安装、卸载、启动、停止和重启。
• HACS 包管理：自定义集成、主题、Python 脚本、AppDaemon 和 NetDaemon 应用。
• 基于令牌的认证、速率限制以及 Docker 支持。

Home Assistant MCP Server 工具

服务器注册了一组精简的动作型工具：

• 设备与状态：list_devices 列出可用设备；control 对某个 entity_id 执行 turn_on、turn_off、toggle 等命令，灯光还可附加 brightness、rgb_color 等参数；get_history 读取历史状态。
• 自动化与场景：automation 管理现有自动化，automation_config 创建、更新或复制自动化，scene 管理并激活场景。
• 系统管理：addon 处理 Supervisor 加载项（list、install、start、stop、restart），package 按类别安装和列出 HACS 包。
• 事件与通知：subscribe_events 和 get_sse_stats 负责 SSE 事件流，notify 发送通知。

Home Assistant MCP Server 的使用场景

• 自然语言控制设备：“把客厅灯打开到 50% 亮度，并设为暖白光。”
• 调节温度：“把温控器设为 21 度，并把空调切换到制热。”
• 用描述的方式创建自动化：“创建一个自动化：检测到移动时打开走廊灯。”
• 检查家里状态：“现在有哪些门和锁是开着的？”
• 维护系统：“列出已安装的加载项并重启 File editor 加载项”，或“安装这个 HACS 集成”。
• 通过 SSE 推送状态变化，实时观察自动化的执行。

Home Assistant MCP Server 与替代方案对比

官方的 Model Context Protocol Server 集成内置于 Home Assistant：在 Settings > Devices & services 中启用后，它会提供一个支持 OAuth 2.0 + PKCE 的 MCP 端点。Claude Code 通过 claude mcp add --transport http home-assistant <your_mcp_server_url> 连接，再运行 claude mcp login home-assistant。它只暴露你共享给助手的实体，并且默认要求管理员账号；Claude 等云端客户端需要你的实例能从互联网访问。对大多数用户来说，官方集成更简单，也有官方支持。这个社区服务器则额外提供了加载项、HACS 和自动化编辑工具，超出了官方 LLM API 的范围。此外还有其他几个社区版 Home Assistant MCP 服务器。

Home Assistant MCP Server 常见问题排查

• toSorted is not a function：Node.js 版本过旧，请升级到 20.10.0 或更高版本（例如 nvm install 20.10.0）。
• 连接问题：确认 Home Assistant 正在运行，运行服务器的机器能访问 HASS_HOST，令牌权限正确；实时更新还需检查 HASS_SOCKET_URL。
• 加载项工具失败：加载项管理需要 Supervisor 访问权限，请确认你的安装中可用，并检查加载项兼容性。
• HACS 工具失败：确认已安装 HACS 且其集成工作正常。
• 自动化报错：检查引用的实体是否存在，核对触发条件和服务调用，并查看日志。