家庭助理Vibecode MCP
⚙️ 此MCP服务器与\ 家居助理Vibecode代理,\ 作为家庭助理插件安装。\ 该代理在您的Home Assistant实例上运行，并为Cursor、VS Code、Claude Code或任何其他启用MCP的IDE等AI IDE提供“眼睛和手”。
让人工智能构建你的家庭助理自动化——或者充当你手写的DevOps。用自然语言描述你需要什么。 🏠🤖
你描述了你的目标→ AI检查您的家庭助理→ 设计定制解决方案→ 并自动将其部署到机载。 🚀
如果你更喜欢自己手工制作自动化和脚本，代理可以简单地充当你的DevOps和额外的帮手：快速上传你的更改、运行测试和按需分析日志。 你保持控制，决定你委托给人工智能多少，以及它应该有多深。
改变您管理智能家居的方式。此插件启用 光标, Visual Studio代码（VS代码），或任何 启用MCP的IDE 致：
- 📝 分析您的家庭助理配置、实体和设备
- 🏗️ 创建智能自动化、脚本和完整的系统，包括可以通过编程完全管理的家庭助理助手
- 🎨 设计和定制Lovelace仪表板，完全控制卡片、布局和样式
- 🖌️ 为个性化UI创建和调整主题
- 🔄 通过基于Git的自动版本控制安全地部署更改
- 🔍 通过日志分析监控和排除安装故障
- 📦 安装和管理HACS集成和自定义存储库
不再需要手动编辑YAML或搜索文档，只需用自然语言描述您想要的内容！
例子： *“为我的散热器安装智能气候控制”* → AI创建了10多个针对TRV优化的自动化、助手、传感器和脚本。
✨ 主要特点
🔍 分析您的设置
✅ 阅读您的完整配置——实体、自动化、脚本、助手\ ✅ 了解您的设备——功能、关系和使用模式\ ✅ 学习现有逻辑——分析当前自动化和脚本的行为方式
______________________________________________________________________
🏗️ 构建智能
✅ 创建完整的系统——在几秒钟内实现多个相互连接的自动化\ ✅ 生成助手和传感器——根据您的实际设置和需求量身定制\ ✅ 编写基于真实实体、区域和设备的优化脚本\ ✅ 重构现有逻辑——改进或合并自动化，而不是从头开始
______________________________________________________________________
📊 仪表板和用户界面
✅ 创建和更新Lovelace仪表板——完全以编程方式\ ✅ 添加、删除或重新排列卡片——统计、图表、历史、自定义卡片等\ ✅ 控制布局和视图--组织房间、区域和场景\ ✅ 设计和调整主题——颜色、排版和风格，以实现个性化的UI
______________________________________________________________________
🔒 安全操作
✅ 基于Git的版本控制——每个更改都会通过有意义的提交消息进行跟踪\ ✅ 人类可读的提交——AI解释 *什么* 改变和 *为什么*\ ✅ 配置验证——应用前测试，以减少破坏性更改\ ✅ 一键回滚——如果出现问题，恢复到以前的状态\ ✅ 活动日志——代理所做工作和时间的完整审计跟踪
______________________________________________________________________
📦 与社区一起扩展
✅ 安装和配置HACS——解锁1000多个社区集成\ ✅ 搜索存储库——主题、插件、自定义组件、仪表板\ ✅ 安装集成--新HACS组件的一个命令设置\ ✅ 保持新鲜感——从一个地方更新所有HACS存储库
______________________________________________________________________
结果：\ 你描述了你的目标→ AI检查您的家庭助理→ 设计定制解决方案→ 并自动将其部署到机载。 🚀
______________________________________________________________________
🚀 这与家庭助理的其他MCP模块有何不同？
我看到的Cursor、VS Code或Claude的大多数MCP集成仅在本地机器上工作，并通过SSH与Home Assistant交谈，有时还通过REST API。
对于严肃的家庭助理工作来说，这还不够：
Home Assistant不仅仅是一堆YAML文件。 它公开了多个内部API，其中一些最重要的API只能通过WebSocket API从HA内部获得。
当您仅通过SSH访问HA时，AI通常必须在每次请求时生成并上传一个辅助脚本，然后在主机上盲目执行。 由于每次脚本都可能不同，因此每个请求都有点像一个黑匣子——更像是玩俄罗斯轮盘赌，而不是进行可靠的自动化。
因此，我选择了一种不同的架构。
这个项目是 分为两个模块:
家庭助理代理 （此模块）-在Home Assistant内部运行（作为附加组件）， 具有对所有相关API、文件和服务的本地访问权限， 并为外部工具提供了一个安全、定义良好的接口。
家庭助理MCP服务器 –在您的计算机上与AI IDE一起运行（游标、VS代码等） 并通过受控制的API而不是SSH破解与代理进行对话（安装步骤如下）
这种设计使使用Home Assistant更快、更可预测、更安全、更可重复。 您的AI IDE通过稳定的API获得所需的操作和数据，而不是不断地发明临时脚本并希望它们正确运行。
______________________________________________________________________
📋 先决条件
安装前，您需要：
- 家庭助手 正在运行（任何版本）
- HA Vibecode代理 v2.2.0+作为附加组件安装
- 代理密钥 来自HA Vibecode代理（首次启动时自动生成）
- 支持AI的编辑器 已安装（游标、VS代码+GitHub副本、Claude代码等）
______________________________________________________________________
🚀 快速入门（5分钟）
步骤0：安装Node.js（如果尚未安装）
MCP服务器需要在您的计算机上运行Node.js（安装了AI编辑器）：
- 检查是否已安装Node.js：打开终端并运行
node --version - 如果未安装或版本低于v20.0.0，请从下载并安装 ** （使用 24.x LTS** 尽可能建造）
- 安装后，验证：
node --version应显示v20.0.0或更高版本（建议使用v24 LTS） - 重要提示： 在运行AI编辑器的计算机上安装Node.js，而不是在Home Assistant服务器上
步骤1：安装HA Vibecode代理
从以下位置在家庭助理中安装代理：
- 首选 设置 → 附加组件 → 附加应用商店
- 点击 ⋮ → 仓库
- 添加：
https://github.com/Coolver/home-assistant-vibecode-agent - 安装 HA Vibecode代理 （v2.0.0+）
- 开始 代理人
步骤2：在AI编辑器中设置MCP
从家庭助理获取配置：
- 打开你的 家庭助手 （通常http://homeassistant.local:8123)
- 首选 设置 → 附加组件 → HA Vibecode代理
- 点击 “打开Web UI” 按钮
- 点击 光标 或 VS Code 选项卡（取决于您要与Home Assistant一起使用的IDE）和 按照设置说明进行操作。您需要安装和配置Cursor或VS Code，以便它们可以通过MCP协议连接到HA代理。
- 就是这样-- 你已经准备好开始了 使用人工智能与您的家庭助理脚本、自动化和仪表板协同工作。
如果你觉得这个项目很有用，并想支持它的发展， 请考虑给它一个 ⭐
步骤3：测试连接
验证一切正常：
打开您的AI编辑器（光标、VS代码等）并将此消息发送给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成功返回您的实体和代理状态，则一切就绪！ ✅
故障排除： 如果连接失败：
- 检查HA Vibecode代理是否正在运行
- 确保您的AI编辑器已完全重新启动
- 验证配置是否正确粘贴
第四步：开始建设！
只需用自然语言描述你想要什么——AI会处理剩下的！
______________________________________________________________________
🔧 配置
环境变量
| 变量 | 描述 | 必填 | 默认 |
|---|---|---|---|
HA_AGENT_URL | HA Vibecode代理的URL | 是 | http://homeassistant.local:8099 |
HA_AGENT_KEY | 用于身份验证的代理密钥 | 是 | - |
自定义代理URL
如果您的代理在其他URL上运行：
{
"mcpServers": {
"home-assistant": {
"command": "npx",
"args": ["-y", "@coolver/home-assistant-mcp@latest"],
"env": {
"HA_AGENT_URL": "http://:8099",
"HA_AGENT_KEY": "your_api_key_here"
}
}
}
}______________________________________________________________________
🐛 故障排除
“代理密钥无效”错误
- 检查您的代理密钥是否正确
mcp.json（根据HA_AGENT_KEY) - 如果需要，重新生成密钥：设置→ 附加组件→ HA Vibecode代理→ 打开Web UI
- 确保HA Vibecode代理正在运行
- 验证代理是否可访问：
curl http://homeassistant.local:8099/api/health
“连接被拒绝”
- 检查家庭助理中的HA Vibecode代理是否已启动
- 验证中的URL
HA_AGENT_URL - 确保端口8099未被防火墙阻止
“spawn npx ENOENT”错误
此错误表示Node.js未安装或在系统PATH中找不到。
解决方案： 安装Node.js（v20.0.0或更高版本； v24 LTS 建议）在运行Cursor的计算机上：
- 从下载并安装Node.js
- 安装后完全重新启动Cursor
- 通过运行验证安装
node --version在终端中
重要提示： Node.js必须安装在 你的电脑 （Cursor、VS Code、Claude或其他IDE运行的地方），而不是在家庭助理服务器上。
______________________________________________________________________
🔐 安全
- ✅ 所有通信均通过HA Vibecode代理（端口8099）进行
- ✅ MCP客户端的代理密钥身份验证
- ✅ 代理验证所有请求的代理密钥
- ✅ 代理使用内部SUPERVISOR_TOKEN执行Home Assistant API操作
- ✅ 您的代理密钥仅存储在本地IDE配置文件中
- ⚠️ 永不承诺
mcp.json用你的代理密钥登录git！
______________________________________________________________________
🤝 相关项目
- HA Vibecode代理 -家庭助理插件（必需）
- 模型上下文协议 -协议规范
______________________________________________________________________
📝 许可证
麻省理工学院©弗拉基米尔·埃雷米夫
______________________________________________________________________
🔧 发展
项目结构
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代理 (https://github.com/Coolver/home-assistant-vibecode-agent)（REST API）← 家庭助理集成
______________________________________________________________________
🙏 贡献
欢迎投稿！请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
______________________________________________________________________
💬 支持
- 🐛 问题：
- 💡 讨论：
______________________________________________________________________
⭐ 表示支持
给一个⭐️ 如果这个项目帮助你用人工智能控制你的智能家居！