home-assistant-mcp

Home Assistant Vibecode MCP

⚙️ 此 MCP 服务与
Home Assistant Vibecode Agent
配合使用，该 Agent 以 Home Assistant 插件的形式安装。
此 Agent 运行在你的 Home Assistant 实例上，可为 Cursor、VS Code、Claude Code 或任何支持 MCP 的 IDE 提供“眼睛和双手”。

让 AI 为你构建 Home Assistant 自动化——也可以担任你手动编写自动化的 DevOps。只需用自然语言描述你的需求。🏠🤖

描述你的目标 → AI 检查你的 Home Assistant → 设计定制解决方案 → 并自动在设备上部署。🚀

如果你更喜欢亲手编写自动化和脚本，Agent 也可以担任你的 DevOps，成为你的得力助手：按需快速上传更改、运行测试并分析日志。由你掌控，决定将多少工作委托给 AI，以及让它参与多深。

改变管理智能家居的方式。此插件让 Cursor、Visual Studio Code (VS Code) 或任何支持 MCP 的 IDE能够：

• 📝 分析你的 Home Assistant 配置、实体和设备
• 🏗️ 创建智能自动化、脚本和完整系统——包括可通过程序全面管理的 Home Assistant 辅助工具
• 🎨 设计和自定义 Lovelace 仪表盘，全面控制卡片、布局和样式
• 🖌️ 创建和调整主题，打造个性化 UI
• 🔄 使用基于 Git 的自动版本控制，安全地部署更改
• 🔍 通过日志分析监控和排查你的设置
• 📦 安装和管理 HACS 集成及自定义存储库

无需再手动编辑 YAML 或搜索文档——只需用自然语言描述你的需求！

示例： “为我的暖气片安装智能温控” → AI 会为你的恒温阀 (TRV) 创建 10 多个经过优化的自动化、辅助工具、传感器和脚本。

基于 Model Context Protocol 构建，由 HA Vibecode Agent 提供支持。

✨ 主要功能

🔍 分析你的设置

✅ 读取完整配置——实体、自动化、脚本、辅助工具
✅ 了解你的设备——功能、关联关系和使用模式
✅ 掌握现有逻辑——分析当前自动化和脚本的运行方式

---

🏗️ 构建智能系统

✅ 创建完整系统——数秒内构建多个相互关联的自动化
✅ 生成辅助工具和传感器——根据你的实际设置和需求量身定制
✅ 编写优化脚本——基于实际实体、区域和设备
✅ 重构现有逻辑——改进或合并自动化，而不是从头开始

---

📊 仪表盘和 UI

✅ 以编程方式创建和更新 Lovelace 仪表盘
✅ 添加、移除或重新排列卡片——包括统计、图表、历史记录、自定义卡片等
✅ 控制布局和视图——整理房间、区域和场景
✅ 设计和调整主题——自定义颜色、字体和样式，打造个性化 UI

---

🔒 安全操作

✅ 基于 Git 的版本控制——每次更改都会以有意义的提交消息记录
✅ 易于理解的提交——AI 会说明更改了什么以及为什么
✅ 配置验证——应用前先测试，以减少配置故障
✅ 一键回滚——出现问题时恢复到先前状态
✅ 活动日志——完整记录 Agent 执行的操作及其时间

---

📦 扩展社区功能

✅ 安装并配置 HACS——解锁 1000+ 个社区集成
✅ 搜索仓库——主题、插件、自定义组件、仪表盘
✅ 安装集成——一键设置新的 HACS 组件
✅ 保持更新——在一个位置更新所有 HACS 仓库

---

结果：
你描述目标 → AI 检查你的 Home Assistant → 设计自定义解决方案 → 并自动将其部署到设备上。🚀

---

🚀 这与其他 Home Assistant MCP 模块有何不同？

我见过的大多数用于 Cursor、VS Code 或 Claude 的 MCP 集成都只能在本地计算机上运行，并通过 SSH（有时也通过 REST API）与 Home Assistant 通信。

对于严肃的 Home Assistant 工作来说，这并不足够：

Home Assistant 不只是一些 YAML 文件。 它提供了多个内部 API，其中一些最重要的 API 只能从 HA 内部通过 WebSocket API 访问。

如果只能通过 SSH 访问 HA，AI 通常每次请求都必须生成并上传一个辅助脚本，然后在主机上盲目执行。 由于每次生成的脚本都可能不同，每个请求都像一个黑箱——这更像是在玩俄罗斯轮盘，而不是进行可靠的自动化。

因此，我选择了不同的架构。

本项目拆分为两个模块：

Home Assistant Agent（本模块）——在 Home Assistant 内部运行（作为加载项）， 可原生访问所有相关 API、文件和服务， 并为外部工具提供安全、定义明确的接口。

Home Assistant MCP 服务——与 AI IDE（Cursor、VS Code 等）一起在你的计算机上运行， 通过受控 API 与 Agent 通信，而不是使用 SSH 变通方案（安装步骤见下文）

这种设计让 Home Assistant 的使用更快捷、更可预测、更安全且可重复。 你的 AI IDE 通过稳定的 API 获取所需的操作和数据，而不是不断临时编写脚本并寄希望于它们能正常运行。

---

📋 前置条件

安装前，你需要：

1. 已运行的 Home Assistant（任意版本）
2. 已将 HA Vibecode Agent v2.2.0+ 安装为加载项
3. 来自 HA Vibecode Agent 的 Agent Key（首次启动时自动生成）
4. 已安装支持 AI 的编辑器（Cursor、VS Code + GitHub Copilot、Claude Code 等）

---

🚀 快速开始（5 分钟）

步骤 0：安装 Node.js（如果尚未安装）

MCP 服务需要 Node.js 才能在你的计算机上运行（即安装了 AI 编辑器的计算机）：

1. 检查是否已安装 Node.js：打开终端并运行 node --version
2. 如果尚未安装或版本低于 v20.0.0，请从 nodejs.org 下载并安装（尽可能选择 24.x LTS 版本）
3. 安装后验证：node --version 应显示 v20.0.0 或更高版本（推荐 v24 LTS）
4. **重要：**请在运行 AI 编辑器的计算机上安装 Node.js，而不是安装在 Home Assistant 服务上

步骤 1：安装 HA Vibecode Agent

在 Home Assistant 中安装 Agent：

1. 前往 设置 → 加载项 → 加载项商店
2. 点击 ⋮ → 仓库
3. 添加：https://github.com/Coolver/home-assistant-vibecode-agent
4. 安装 HA Vibecode Agent（v2.0.0+）
5. 启动 Agent

步骤 2：在 AI 编辑器中设置 MCP

从 Home Assistant 获取配置：

1. 打开你的 Home Assistant（通常为 http://homeassistant.local:8123）
2. 前往 设置 → 加载项 → HA Vibecode Agent
3. 点击 “打开 Web UI” 按钮
4. 点击 Cursor 或 VS Code 选项卡（取决于你想使用哪个 IDE 与 Home Assistant 配合），并按照设置说明操作。你需要安装并配置 Cursor 或 VS Code，以便它们通过 MCP 协议连接到 HA Agent。
5. 就这样——你已准备就绪，可以开始使用 AI 处理 Home Assistant 脚本、自动化和仪表盘了。 如果你觉得这个项目有用，并想支持其开发，请考虑为它点亮一个 GitHub Star ⭐

步骤 3：测试连接

确认一切正常：

打开你的 AI 编辑器（Cursor、VS Code 等），并向 AI 发送以下消息：

Connect to my Home Assistant and show me:
1. List of all my climate entities
2. Current status of the HA Vibecode Agent

This will verify the MCP connection is working.

如果 AI 成功返回你的实体和 Agent 状态，就说明一切准备就绪！✅

**故障排除：**如果连接失败：

• 检查 HA Vibecode Agent 是否正在运行
• 确保已完全重启 AI 编辑器
• 确认配置粘贴正确

步骤 4：开始构建！

只需用自然语言描述你的需求——AI 会处理其余部分！

---

🔧 配置

环境变量

变量	说明	必需	默认值
HA_AGENT_URL	HA Vibecode Agent 的 URL	是	http://homeassistant.local:8099
HA_AGENT_KEY	用于身份验证的 Agent Key	是	-

自定义 Agent URL

如果你的 Agent 运行在其他 URL：

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@coolver/home-assistant-mcp@latest"],
      "env": {
        "HA_AGENT_URL": "http://<home-assistant-host>:8099",
        "HA_AGENT_KEY": "your_api_key_here"
      }
    }
  }
}

---

🐛 故障排除

“Invalid Agent Key”错误

1. 检查 mcp.json 中的 Agent Key 是否正确（位于 HA_AGENT_KEY 下）
2. 如有需要，重新生成密钥：设置 → 加载项 → HA Vibecode Agent → 打开 Web UI
3. 确保 HA Vibecode Agent 正在运行
4. 确认 Agent 可访问：curl http://homeassistant.local:8099/api/health

“Connection refused”

1. 检查 Home Assistant 中的 HA Vibecode Agent 是否已启动
2. 确认 HA_AGENT_URL 中的 URL
3. 确保防火墙未阻止端口 8099

“spawn npx ENOENT”错误

此错误表示系统中未安装 Node.js，或系统 PATH 中找不到 Node.js。

**解决方案：**在运行 Cursor 的计算机上安装 Node.js（v20.0.0 或更高版本；推荐使用 v24 LTS）：

1. 从 https://nodejs.org 下载并安装 Node.js
2. 安装完成后彻底重启 Cursor
3. 在终端中运行 node --version，验证是否安装成功

重要：必须在你的计算机（运行 Cursor、VS Code、Claude 或其他 IDE 的计算机）上安装 Node.js，而不是安装在 Home Assistant 服务端上。

---

🔐 安全

• ✅ 所有通信均通过 HA Vibecode Agent（端口 8099）进行
• ✅ MCP 客户端使用 Agent Key 进行身份验证
• ✅ Agent 会验证所有请求中的 Agent Key
• ✅ Agent 使用内部 SUPERVISOR_TOKEN 执行 Home Assistant API 操作
• ✅ 你的 Agent Key 仅存储在本地 IDE 配置文件中
• ⚠️ 切勿将包含 Agent Key 的 mcp.json 提交到 git！

---

🤝 相关项目

• HA Vibecode Agent - Home Assistant 加载项（必需）
• Model Context Protocol - 协议规范

---

📝 许可证

MIT © Vladimir Eremeev

---

🔧 开发

项目结构

home-assistant-mcp/
├── package.json            # NPM package config
├── tsconfig.json           # TypeScript config
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── ha-client.ts       # HA Agent API client
│   ├── handlers.ts        # Tool request handlers
│   ├── tools.ts           # Legacy tool definitions
│   └── tools/             # Modular tool definitions
│       ├── index.ts       # Tool exports
│       ├── files.ts       # File operation tools
│       ├── system.ts      # System operation tools
│       └── dashboard.ts   # Dashboard tools
├── build/                 # Compiled JavaScript output
├── README.md
├── CHANGELOG.md
└── QUICK_START.md

架构

MCP 服务端（index.ts）← 通信协议
↓
工具处理程序（handlers.ts）← 业务逻辑
↓
HA 客户端（ha-client.ts）← HTTP API 封装
↓
HA Vibecode Agent（https://github.com/Coolver/home-assistant-vibecode-agent）（REST API）← Home Assistant 集成

---

🙏 参与贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 将更改推送到分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

---

💬 支持

• 🐛 问题：GitHub Issues
• 💡 讨论：GitHub Discussions

---

⭐ 表达支持

如果这个项目帮助你通过 AI 控制智能家居，请点个 ⭐️！