English | 中文

Home Assistant MCP Server

通过 MCP (Model Context Protocol) 让 AI Agent 直接控制你的 Home Assistant 智能家居设备。

零外部依赖 — 只需要 Node.js 18+。

前置要求

• Node.js 18+
• 正在运行的 Home Assistant 实例
• Home Assistant 长期访问令牌（Long-Lived Access Token）

工具

工具	功能	必需参数	可选参数
ha_call_service	调用 HA 服务（开关灯、调温度等）	domain, service	url, token, body
ha_get_states	获取实体状态	—	url, token, entity_id
ha_lookup_service	查询服务参数信息	—	domain, service

所有工具都支持通过参数 url 和 token 传入 HA 凭证，也支持通过环境变量 HA_URL 和 HA_TOKEN 设置默认值。

快速开始

git clone https://github.com/weyand138-netizen/Home-assistant-AI-agent-mcp.git
cd Home-assistant-AI-agent-mcp

# 直接运行（无需 npm install）
node ha-mcp-server.mjs

在支持 MCP 的客户端中使用

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "ha": {
      "command": "node",
      "args": ["路径/ha-mcp-server.mjs"],
      "env": {
        "HA_URL": "http://192.168.1.100:8123",
        "HA_TOKEN": "你的长期访问令牌"
      }
    }
  }
}

其他 MCP 客户端

在任何支持 MCP stdio 传输的客户端中，按相同方式配置即可。也可以不设置环境变量，在对话中直接传参：

"把客厅灯打开，HA 地址是 http://192.168.1.100:8123，令牌是 xxxxx"

测试

# 启动服务器
node ha-mcp-server.mjs

# 也可以用 MCP Inspector 调试
npx @modelcontextprotocol/inspector node ha-mcp-server.mjs

工作原理

AI Agent → MCP stdio (JSON-RPC 2.0) → ha-mcp-server.mjs
                                         → Node.js fetch（无 CORS 限制）
                                         → HA REST API（port 8123）
                                         → 智能家居设备

服务字典

内置 32 个 domain、100+ 个服务的参数信息。包含 homeassistant、light、switch、climate、shopping_list、todo、scene、automation 等常用领域。

如需更新字典，可在 HA 中执行 curl http://your-ha:8123/api/services，按格式整理后替换 ha-service-dict.mjs。

License

MIT

---

我只是初学者，这个做得可能不太好，欢迎指正 🙏