星战科技xingzhan.cloud
返回市场
家庭助手mcp

家庭助手mcp

作者：Coolver2 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

MCP Home Assistant

通过人工智能构建智能家居自动化——只需用自然语言描述您想要的功能 🏠🤖

转变您的智能家居管理！此MCP服务器使Cursor AI能够：

  • 📝 分析您的Home Assistant配置和设备
  • 🏗️ 创建智能自动化、脚本和完整的系统
  • 🔍 通过日志分析进行监控和故障排除
  • 📦 安装和管理HACS集成（超过1000个自定义集成！）
  • 🔄 使用自动Git版本控制安全部署更改

无需手动编辑YAML或在文档中搜索！

示例： "为我的散热器安装智能气候控制系统" → AI创建了10多个针对您TRV的优化自动化、辅助程序、传感器和脚本。

基于Model Context Protocol并由HA Cursor Agent驱动。

NPM 版本 许可证: MIT

✨ 主要功能

  • 🤖 自然语言 — 描述您想要的内容，AI会为您构建
  • 🎯 设备感知 — 分析您的实际设置
  • 📦 HACS 集成 — 通过WebSocket安装和管理1000多个自定义集成
  • 💾 自动备份 — 每次更改都会自动保存到Git
  • ⏪ 即时回滚 — 通过一个命令恢复到任何先前版本
  • 🔄 组件管理 — 自动化、脚本、辅助程序、实体
  • 📊 日志分析 — 监控系统行为，检测异常，提出优化建议
  • 🐛 调试辅助 — AI自动读取日志并识别问题

🎯 您可以做什么？

Cursor AI分析您的实际Home Assistant配置，并创建针对您设备的智能自动化：

🏗️ 从零开始构建复杂系统

  • 💬 "安装HACS，然后安装Xiaomi Gateway 3集成"
  • 💬 "为我的TRV散热器安装具有预测关闭和缓冲模式的智能气候控制系统"
  • 💬 "使用我的运动传感器和时间表创建基于存在的照明系统"
  • 💬 "设置能耗监控，在消耗量高时发送通知"

AI将：

  1. ✅ 读取您的当前配置
  2. ✅ 检测您的设备和实体
  3. ✅ 创建自动化、脚本、辅助程序
  4. ✅ 测试和验证一切
  5. ✅ 部署 — 全部自动完成！

📦 扩展社区集成

  • 💬 "为我安装HACS"
  • 💬 "在HACS中搜索Xiaomi集成"
  • 💬 "从HACS安装Xiaomi Gateway 3"
  • 💬 "HACS中有哪些主题？"
  • 💬 "更新我所有的HACS存储库"

AI将：

  1. ✅ 自动安装HACS
  2. ✅ 搜索1000多个社区存储库
  3. ✅ 安装集成、主题、插件
  4. ✅ 保持一切更新

🔌 管理附加组件和服务

  • 💬 "安装Zigbee2MQTT并为我的Sonoff适配器配置它"
  • 💬 "设置Mosquitto MQTT代理"
  • 💬 "安装Node-RED以实现可视化自动化"
  • 💬 "我的Zigbee2MQTT无法工作，请检查日志并修复"
  • 💬 "更新我所有的附加组件"

AI将：

  1. ✅ 安装附加组件（Zigbee2MQTT、Node-RED、ESPHome）
  2. ✅ 自动检测硬件（USB协调器）
  3. ✅ 配置选项
  4. ✅ 启动/停止/重启服务
  5. ✅ 监控日志并进行故障排除

🔧 智能配置

  • 💬 "根据房间优先级和占用模式优化我的供暖系统"
  • 💬 "使用我实际的灯光和媒体设备创建电影之夜智能场景"
  • 💬 "使用我的门传感器和摄像头构建安全系统"

🐛 调试和解决问题

  • 💬 "为什么我的卧室自动化不起作用？检查日志并修复"
  • 💬 "我的气候控制总是提前关闭，分析并改进逻辑"

📊 监控和分析

  • 💬 "分析我的日志，告诉我我的供暖系统是否高效运行"
  • 💬 "检查我的自动化是否触发过于频繁或错过事件"
  • 💬 "比较实际系统行为与预期逻辑，并提出改进建议"

无需手动编辑YAML。无需复制粘贴。只需描述您想要的内容！ 🚀

📋 前提条件

在安装之前，您需要：

  1. 运行中的Home Assistant（任何版本）
  2. 安装作为附加组件的**HA Cursor Agent** v2.2.0+
  3. 从HA Cursor Agent获取Agent Key（首次启动时自动生成）
  4. 安装Cursor AI编辑器

🚀 快速入门（5分钟）

第一步：安装HA Cursor Agent

在您的Home Assistant中安装代理：

  1. 转到设置 → 附加组件 → 附加组件商店
  2. 点击**⋮** → 存储库
  3. 添加：https://github.com/Coolver/home-assistant-cursor-agent
  4. 安装HA Cursor Agent（v2.0.0+）
  5. 启动代理

第二步：在Cursor中设置MCP

从Home Assistant获取配置：

  1. 打开您的Home Assistant（通常为http://homeassistant.local:8123）
  2. 转到设置 → 附加组件 → HA Cursor Agent
  3. 点击**"打开Web UI"**按钮
  4. 点击**"复制配置到剪贴板"**
  5. 配置已复制！✅

添加到Cursor AI：

  1. 打开Cursor编辑器
  2. 转到设置（Cmd/Ctrl + ,）
  3. 在侧边栏点击工具 & MCP
  4. 点击新建MCP服务器
  5. 粘贴您复制的配置
  6. 点击保存
  7. 完全重新启动Cursor（Cmd/Ctrl + Q 并重新打开）

参考配置如下：

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@coolver/home-assistant-mcp@latest"],
      "env": {
        "HA_AGENT_URL": "http://homeassistant.local:8099",
        "HA_AGENT_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

注意： Web UI提供了可以直接复制的精确配置 — 不需要手动输入！

完成！Cursor AI现在连接到您的Home Assistant 🎉

第三步：测试连接

验证一切正常：

打开Cursor并向AI发送以下消息：

连接到我的Home Assistant并显示：
1. 我的所有气候实体列表
2. HA Cursor Agent的当前状态

这将验证MCP连接是否正常。

如果AI成功返回您的实体和代理状态，则一切就绪！✅

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

  • 检查HA Cursor Agent是否正在运行
  • 确保完全重新启动了Cursor
  • 验证配置是否正确粘贴

第四步：开始构建！

只需用自然语言描述您想要的内容 — AI将处理其余部分！

💬 实际案例

一旦配置好，只需用自然语言描述您想要的内容。Cursor AI将分析您的配置并创建定制解决方案：

📦 HACS & 集成（v2.2.0新功能！）🔥

通过WebSocket完整管理HACS — 浏览1000多个集成！

为我安装HACS

AI将：

  • 检查HACS是否已经安装
  • 从GitHub下载最新HACS发布版
  • 提取到custom_components/hacs
  • 重启Home Assistant
  • 等待WebSocket连接
  • 验证安装 ✅
在HACS中搜索Xiaomi集成

AI将：

  • 通过WebSocket连接
  • 搜索HACS存储库数据库
  • 显示匹配的集成，包括：
    • 存储库名称
    • 描述
    • 星数评级
    • 当前版本
    • 安装状态
从HACS安装Xiaomi Gateway 3集成

AI将：

  • 验证HACS是否已安装
  • 通过WebSocket调用hacs.download服务
  • 下载并安装集成
  • 通知重启需求
  • 引导您完成配置
  • 创建示例自动化
更新我所有的HACS集成

AI将：

  • 调用hacs.update_all服务
  • 下载所有可用更新
  • 通知重启
  • 显示更新内容

完整流程：

用户："安装HACS，然后安装Xiaomi Gateway 3并创建自动化"

AI：
1. 从GitHub安装HACS ✅
2. 重启Home Assistant ✅
3. 等待连接 ✅
4. 搜索“Xiaomi Gateway 3” ✅
5. 安装集成 ✅
6. 引导UI配置 ✅
7. 为您的设备创建自动化 ✅

✨ 由WebSocket驱动 — 实时访问HACS数据！

🏗️ 安装完整系统

为我家安装智能气候控制系统。
分析我的TRV散热器，创建高效的加热自动化，
并设置仪表盘。

AI将：

  • 检测您的TRV实体
  • 创建8-10个智能加热自动化
  • 添加辅助实体以监测系统状态
  • 创建模板传感器以监测
  • 设置锅炉控制脚本
  • 生成Lovelace仪表盘
  • 测试并部署
使用我的手机追踪器构建存在检测系统，
并为灯光、气候和安全创建自动化。

AI将：

  • 查找您的device_tracker实体
  • 创建区域和存在辅助程序
  • 设置每个房间的灯光自动化
  • 根据存在情况配置气候
  • 添加安全通知
  • 全部针对您的设备！

🔧 优化现有系统

我的供暖系统浪费能源。分析我当前的自动化，
并优化效率同时保持舒适度。

AI将：

  • 读取当前自动化
  • 分析供暖模式
  • 添加预测逻辑
  • 实现自适应冷却
  • 保持您的现有设置不变

🐛 调试和解决问题

我的卧室灯光自动化没有正常工作。
检查日志，分析自动化，并解决这个问题。

AI将：

  • 读取自动化配置
  • 检查实体状态
  • 查看代理日志中的错误
  • 识别问题
  • 解决并测试解决方案

📊 监控和分析系统行为

Cursor AI可以读取日志并分析您的系统实际如何工作：

读取日志并分析我的气候控制系统的表现。
它是否按预期工作？

AI将：

  • 读取Home Assistant日志
  • 分析自动化触发和动作
  • 对比实际行为与预期逻辑
  • 识别偏差或低效之处
  • 提供详细的性能报告
我的供暖系统似乎效率低下。分析过去一天的日志并提出改进建议。

AI将：

  • 提取相关日志条目
  • 识别模式（频繁的开关循环、定时问题）
  • 检测边缘情况或意外行为
  • 计算指标（运行时间、循环次数、效率）
  • 提出具体的优化建议
监控我的自动化并告诉我它们是否触发过于频繁或错过重要事件。

AI将：

  • 跟踪自动化执行频率
  • 识别过度触发或触发不足
  • 发现缺失条件或边缘情况
  • 推荐调整触发器和条件

使用案例：

  • 🔍 性能审计 — “我的自动化运行效率吗？”
  • ⚠️ 异常检测 — “昨天发生了什么不寻常的事情？”
  • 📈 使用分析 — “我的安全系统触发了多少次？”
  • 🎯 优化 — “我们能否减少自动化运行次数？”
  • 🐛 根本原因分析 — “为什么锅炉意外关闭？”

🎨 创建自定义解决方案

我想有电影模式：调暗所有灯光，关闭百叶窗，
打开电视和音响。创建场景和自动化。

AI将：

  • 检测您的灯光、覆盖物、媒体设备
  • 创建用于电影模式的input_boolean
  • 构建包含所有步骤的自动化
  • 添加易于激活的脚本
  • 根据您的设备进行定制

💾 Git版本控制及回滚

每次更改都会自动备份到Git！ 您可以随时查看历史记录并回滚。

显示我配置的最后10次更改

AI将：

  • 显示提交历史及其消息
  • 展示更改内容和时间
  • 帮助您识别特定版本
出了问题！回滚到昨天的版本

AI将：

  • 显示最近的提交
  • 找到昨天的提交
  • 回滚您的配置
  • 验证一切正常
显示提交abc123中的更改

AI将：

  • 显示该提交的详细差异
  • 解释修改了哪些文件
  • 帮助您理解更改

可用的Git工具：

  • ha_git_history — 查看提交历史（最后20个提交）
  • ha_git_diff — 比较提交或查看未提交的更改
  • ha_git_rollback — 恢复到任何先前版本
  • ha_git_commit — 手动备份并附带自定义消息

示例工作流程：

  1. 进行更改 → 自动备份 ✅
  2. 出问题了？ → 请AI显示历史记录
  3. AI显示提交 → 您识别好的版本
  4. AI回滚 → 一切恢复！🎉

🔧 配置

环境变量

变量描述是否必需默认值
HA_AGENT_URLHA Cursor Agent的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://192.168.1.100:8099",
        "HA_AGENT_KEY": "your_api_key_here"
      }
    }
  }
}

🛠️ 可用工具

MCP服务器向Cursor AI提供这些工具：

📁 文件

  • ha_read_file — 读取配置文件
  • ha_write_file — 写入配置文件
  • ha_list_files — 列出目录中的文件
  • ha_delete_file — 删除文件

🏠 实体

  • ha_list_entities — 列出所有实体（可按域过滤）
  • ha_get_entity_state — 获取特定实体的状态

🔧 辅助程序

  • ha_list_helpers — 列出所有输入辅助程序
  • ha_create_helper — 创建新的输入辅助程序
  • ha_delete_helper — 删除辅助程序

🤖 自动化

  • ha_list_automations — 列出所有自动化
  • ha_create_automation — 创建新的自动化
  • ha_delete_automation — 删除自动化

📜 脚本

  • ha_list_scripts — 列出所有脚本
  • ha_create_script — 创建新的脚本
  • ha_delete_script- 删除脚本

🔄 系统

  • ha_check_config — 检查配置的有效性
  • ha_reload_config — 重新加载配置
  • ha_get_logs — 获取代理日志

💾 备份

  • ha_git_commit — 将更改提交到git
  • ha_git_history — 查看git历史
  • ha_git_rollback — 回滚到先前版本
  • ha_git_diff — 比较提交或查看更改

📦 HACS（由WebSocket驱动）

  • ha_install_hacs — 从GitHub安装HACS
  • ha_hacs_status — 检查安装状态
  • ha_hacs_list_repositories — 列出所有存储库（按类别过滤）
  • ha_hacs_search — 按查询搜索存储库
  • ha_hacs_install_repository — 安装集成/主题/插件
  • ha_hacs_update_all — 更新所有已安装的存储库
  • ha_hacs_repository_details — 获取详细的存储库信息

🐛 故障排除

"无效代理密钥"错误

  1. 检查您的代理密钥是否正确（在mcp.json下的HA_AGENT_KEY）
  2. 如需重新生成密钥：设置 → 附加组件 → HA Cursor Agent → 打开Web UI
  3. 确保HA Cursor Agent正在运行
  4. 验证代理是否可访问：`curl http://homeassistant.local