AI导哈

智能家居自动化工具

Home Assistant Vibecode MCP是一款智能家居自动化工具，通过与AI IDE集成，允许用户通过自然语言描述来自动创建、管理和部署Home Assistant的自动化脚本、仪表板和主题。

  • by Coolver
  • TypeScript
  • 本地部署
  • 58 星标
  • 更新于
在 GitHub 查看 Coolver/mcp-home-assistant

使用说明

家庭助理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优化的自动化、助手、传感器和脚本。

建于 模型上下文协议 并由 HA Vibecode代理.

✨ 主要特点

🔍 分析您的设置

✅ 阅读您的完整配置——实体、自动化、脚本、助手
✅ 了解您的设备——功能、关系和使用模式
✅ 学习现有逻辑——分析当前自动化和脚本的行为方式

🏗️ 构建智能

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

📊 仪表板和用户界面

✅ 创建和更新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获得所需的操作和数据，而不是不断地发明临时脚本并希望它们正确运行。

📋 先决条件

安装前，您需要：

  1. 家庭助手 正在运行（任何版本）
  2. HA Vibecode代理 v2.2.0+作为附加组件安装
  3. 代理密钥 来自HA Vibecode代理（首次启动时自动生成）
  4. 支持AI的编辑器 已安装（游标、VS代码+GitHub副本、Claude代码等）

🚀 快速入门（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代理

从以下位置在家庭助理中安装代理：

  1. 首选 设置 → 附加组件 → 附加应用商店
  2. 点击 ⋮ → 仓库
  3. 添加： https://github.com/Coolver/home-assistant-vibecode-agent
  4. 安装 HA Vibecode代理 （v2.0.0+）
  5. 开始 代理人

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

从家庭助理获取配置：

  1. 打开你的 家庭助手 （通常http://homeassistant.local:8123)
  2. 首选 设置 → 附加组件 → HA Vibecode代理
  3. 点击 “打开Web UI” 按钮
  4. 点击 光标 或 VS Code 选项卡（取决于您要与Home Assistant一起使用的IDE）和 按照设置说明进行操作。您需要安装和配置Cursor或VS Code，以便它们可以通过MCP协议连接到HA代理。
  5. 就是这样-- 你已经准备好开始了 使用人工智能与您的家庭助理脚本、自动化和仪表板协同工作。 如果你觉得这个项目很有用，并想支持它的发展， 请考虑给它一个 GitHub之星 ⭐

步骤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://<home-assistant-host>:8099",
        "HA_AGENT_KEY": "your_api_key_here"
      }
    }
  }
}

🐛 故障排除

“代理密钥无效”错误

  1. 检查您的代理密钥是否正确 mcp.json （根据 HA_AGENT_KEY)
  2. 如果需要，重新生成密钥：设置→ 附加组件→ HA Vibecode代理→ 打开Web UI
  3. 确保HA Vibecode代理正在运行
  4. 验证代理是否可访问： curl http://homeassistant.local:8099/api/health

“连接被拒绝”

  1. 检查家庭助理中的HA Vibecode代理是否已启动
  2. 验证中的URL HA_AGENT_URL
  3. 确保端口8099未被防火墙阻止

“spawn npx ENOENT”错误

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

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

  1. 从下载并安装Node.js https://nodejs.org
  2. 安装后完全重新启动Cursor
  3. 通过运行验证安装 node --version 在终端中

重要提示： Node.js必须安装在 你的电脑 （Cursor、VS Code、Claude或其他IDE运行的地方），而不是在家庭助理服务器上。

🔐 安全

  • ✅ 所有通信均通过HA Vibecode代理（端口8099）进行
  • ✅ MCP客户端的代理密钥身份验证
  • ✅ 代理验证所有请求的代理密钥
  • ✅ 代理使用内部SUPERVISOR_TOKEN执行Home Assistant API操作
  • ✅ 您的代理密钥仅存储在本地IDE配置文件中
  • ⚠️ 永不承诺 mcp.json 用你的代理密钥登录git！

🤝 相关项目

📝 许可证

麻省理工学院©弗拉基米尔·埃雷米夫

🔧 发展

项目结构

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）← 家庭助理集成

🙏 贡献

欢迎投稿！请随时提交拉取请求。

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 提交您的更改(git commit -m 'Add some AmazingFeature')
  4. 推到分支(git push origin feature/AmazingFeature)
  5. 打开拉取请求

💬 支持

⭐ 表示支持

给一个⭐️ 如果这个项目帮助你用人工智能控制你的智能家居！

相关 MCP