# @coolver/home-assistant-mcp 中文文档

规范地址：https://npmcn.com/package/%40coolver/home-assistant-mcp/

版本：3\.2\.32
npm 元数据更新时间：2026-10-21T23:28:50.395Z
中文译文更新时间：2026-11-10T22:29:47.806Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40coolver/home-assistant-mcp
原文对照：https://npmcn.com/package/%40coolver/home-assistant-mcp/?lang=original
项目主页：https://github.com/Coolver/home-assistant-mcp#readme
源码仓库：https://github.com/Coolver/home-assistant-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：285 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- 首次发布：2025-11-10T12:17:35.072Z
- 最新版本发布：2026-10-21T23:28:50.062Z
- 近 30 天下载量：2547（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 34 个）

## 中文简介

启用 Cursor, VS 代码, Claude 代码或任何 MCP 启用的 IDE 来帮助您进行气相编码和管理家用助理: 创建自动化, 设计仪表板, 调整主题, 修改配置并使用自然语言部署更改

## 安装

```sh
npm install @coolver/home-assistant-mcp
```

也可以使用：`pnpm add @coolver/home-assistant-mcp`、`yarn add @coolver/home-assistant-mcp`、`bun add @coolver/home-assistant-mcp`

## README

# 家庭助理 Vibecode MCP

[![NPM Version](https://img.shields.io/npm/v/@coolver/home-assistant-mcp)](https://www.npmjs.com/package/@coolver/home-assistant-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> 此 MCP 服务器与  
> [家庭助理 Vibecode 代理服务器](https://github.com/Coolver/home-assistant-vibecode-agent), (中文(简体) ),  
> 安装为家庭助理.  
> 该代理商运行在您的家庭助理实例上,为AI IDE提供"眼睛和手",如Cursor,VS代码,克洛德代码,或任何其他由MCP驱动的IDE.

**让AI建立你的家庭助理自动化系统, 用自然语言来描述你需要什么 🏠🤖**

您描述您的目标 – AI检查您的家庭助理 – 设计自定义解决方案 – 并自动在机上部署

如果你更喜欢自己手动自动化和脚本,代理可以简单地作为您的DevOps和额外的一对手:快速上传您的修改,运行测试,以及按需分析日志. **你继续控制,决定你给AI授权多少 和它应该有多深.**

改变你管理聪明家的方式 此添加启用 **光标**, (中文(简体) ), **视觉工作室代码( VS 代码)**,或任何 **MCP 启用的IDE** 改为:

-   分析您的家用助理配置、 实体和设备
-   · 建立智能自动化、脚本和完整的系统——包括可以全程管理的家庭助理助手
-   \* 设计和定制Lovelace仪表板,全面控制卡片、布局和样式
-   QQ 为个性化的 UI 创建并调整主题
-   QQ 使用基于 Git 的自动版本安全部署更改
-   QQ 监视器和通过日志分析排除您的设置出问题
-   \* 安装和管理HACS集成和自定义寄存器

不再手动YAML编辑或搜索文档 - 用自然语言描述你想要的东西!

**示例** _为我的散热器安装智能气候控制器_ + AI为您TRV创建了10+自动化,辅助器,传感器和脚本优化.

建造在 [示范背景协议](https://modelcontextprotocol.io/) 和动力 [HA 密码代理](https://github.com/Coolver/home-assistant-cursor-agent)。 。 。 .

### 关键特性

### 分析你的设置

QQ 读取您的完整配置—— 实体、 自动化、 脚本、 助手  
了解你的设备——能力、关系和使用模式  
QQ 学习现有逻辑 – 分析您当前自动化和脚本的表现

* * *

### 建立智能

QQ 创建完整的系统——数秒的多个互联自动化  
✅ 生成帮助器和传感器——适合您的实际设置和需要  
QQ 编写优化的脚本——基于真实的实体,区域,设备  
\* 修改现有逻辑——改进或合并自动化而不是从零开始

* * *

### & UI 磁盘板

· 建立和更新Lovelace仪表板——完全按程序  
+++ 添加、去除或重排卡片——统计、图表、历史、定制卡等  
\* 控制布局和观点——安排房间、区域和情景  
• 设计与调整主题——个性化UI的颜色、打字和风格

* * *

### 安全作业

QQ基于 Git 的版本——每个变化都用有意义的承诺信息跟踪  
• 人类可读承诺——大赦国际解释 _什麽_ 已更改和 _为什么_  
QQ 配置验证 — 应用前的测试以减少中断更改  
QQ 一击回滚——如果出事恢复到先前状态  
\* 活动记录——关于代理人所作所为和何时所作所为的全部审计线索

* * *

### 与社区联系

\* 安装和配置HACS——解锁1000+社区一体化  
\* 搜索寄存器——主题、插件、自定义组件、仪表板  
\* 安装集成装置——为新的HACS组件设置一个指令  
QQ 保持新鲜- 从一个地方更新所有 HACS 寄存器

* * *

**结果 :**  
您描述您的目标 – AI检查您的家庭助理 – 设计自定义解决方案 – 并自动在机上部署

* * *

### 这与其他家庭助理的MCP模块有什么不同?

我所看到的大多数MCP集成, VS代码或克洛德只工作在您的本地机器上.

家庭助理的工作很严肃

家庭助理不仅仅是一堆YAML文件. 它暴露出多个内部API,一些最重要的部分只能从HA内部通过WebSocket API获得.

当您仅通过SSH访问HA时,AI通常必须在每次请求上生成并上传一个帮助脚本,然后在主机上盲目地执行. 由于这个脚本每次都可以不同,所以每个请求都有点像黑匣子——比起做可靠的自动化,更像是玩俄罗斯的轮盘.

因此,我选择了一个不同的建筑.

这个项目是 **分为两个模块**数字 :

**家庭助理探员** (本单元)-在家庭助理内部运行(作为附加), \* 本地人可以使用所有相关的API、文档和服务, 并曝光外部工具的安全,明确定义的界面.

**家用助理 MCP 服务器** – 运行在您的计算机上, 同时运行您的 AI IDE( 课程、 VS 代码等) 和特工讨论控制下的API而不是SSH黑客(下面安装步骤)

这种设计使得与家庭助理的合作更快,更可预测,更安全并可以重复. 您的 AI IDE 通过稳定的 API 获得它需要的精确动作和数据, 而不是不断地发明 临时的脚本, 希望它们行为正确 .

* * *

## · 先决条件

安装前需要:

1.  **家庭助理** 运行( 任何版本)
2.  **[HA 密码代理](https://github.com/Coolver/home-assistant-vibecode-agent)** v2.2.0+ 作为加载安装
3.  **代理密钥** 从 HA Vibecode 代理( 启动时自动生成)
4.  **AI 启用编辑器** 已安装( Cursor, VS 代码 + GitHub 副驾驶, Claude 代码等)

* * *

## QQ快起步( 5分钟)

### 第0步:安装节点.js(如果尚未安装)

MCP 服务器要求 Node.js 运行在您的计算机上( 安装了您的 AI 编辑器) :

1.  检查Node.js是否已经安装: 打开终端并运行 `node --version`
2.  如果未安装或版本低于v20.0.0,则从 **[节点js.org](https://nodejs.org/)** (使用 **24.x 长期服务** 尽可能建立)
3.  安装后,核实: `node --version` 应显示 v20.0.0 或更高( 建议的 v24 LTS)
4.  **重要内容:** 在运行您的 AI 编辑器的计算机上安装节点. js, 不在 Home 助理服务器上

### 第1步:安装 HA 密码代理

从 :

1.  转到 **设置** → **加进** → **添加存储**
2.  点击 **⋮** → **仓库**
3.  添加: `https://github.com/Coolver/home-assistant-vibecode-agent`
4.  安装 **HA 密码代理** (v2.0.0+) (中文(简体) )
5.  **开始** 代理人

### 步骤2: 在您的 AI 编辑器中设置 MCP

**从家用助理获取配置 :**

1.  打开你的 **家庭助理** (通常为http://homeassistant.local:8123)
2.  转到 **设置** → **加进** → **HA 密码代理**
3.  点击 **"开放网络用户界面"** 按钮
4.  点击 **光标** 或者说 **VS 代码** 选项卡(取决于您想与家用助理一起使用的IDE)和 **遵循设置指令**您需要安装和配置光标或 VS 代码, 以便通过 MCP 协议连接到 HA 代理 .
5.  就这样: **您已经准备好开始** 使用人工智能与家庭助理的脚本、自动化和仪表板合作. 如果你认为这个项目有用 并想支持它的开发, **请考虑给它一个 [GitHub 星号](https://github.com/Coolver/home-assistant-mcp) ⭐**

### 第3步:测试连接

**校验所有工作**

打开您的 AI 编辑器( Cursor, 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 成功返回您的实体和代理身份, 你们都准备好了 ! @ @ @ info: whatsthis

**解决问题:** 如果连接失败 :

-   检查HA Vibecode 代理正在运行
-   确保您的 AI 编辑器完全重新启动
-   校验配置已正确粘贴

### 第4步:开始建设!

用自然语言描述你想要的东西 - AI会处理其他的!

* * *

## QQ 配置

### 环境变量

| 变量 | 说明 | 需求 | 默认 |
| --- | --- | --- | --- |
| `HA_AGENT_URL` | HA 密码代理的 URL | 对 | `http://homeassistant.local:8099` |
| `HA_AGENT_KEY` | 认证代理密钥 | 对 | \- 说吧 |

### 自定义代理 URL

如果您的代理运行在不同的 URL 上 :

```json
{
  "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.  需要时重新生成密钥: 设置 → 添加- ons → HA Vibecode Agent → 打开网络用户界面
3.  确保HA Vibecode 代理运行
4.  校验代理可访问 : `curl http://homeassistant.local:8099/api/health`

### "拒绝接通"

1.  请检查access-date=中的日期值 (帮助) HA Vibecode Agent in Home Assistance
2.  校验 URL 在 `HA_AGENT_URL`
3.  确保8099端口没有被防火墙封锁

### “ sprawn npx ENOENT” 错误

此错误意味着在您的系统 PATH 中没有安装或找不到 Node.js .

**解决方案 :** 安装节点.js(v20.0.0或以上); **v24 长期服务** cursor 运行的计算机上:

1.  下载并安装节点.js from [https://nodejs.org (英语)](https://nodejs.org/)
2.  安装后完全重新启动光标
3.  通过运行验证安装 `node --version` 在终端

**重要内容:** 节点.js必须安装在 **您的电脑** (其中Cursor,VS代码,克洛德或其他IDE运行),不在Home Asserver上.

* * *

## • 警卫

-   所有通讯通过HA Vibecode Agent(8099港)
-   MCP 客户端的代理密钥认证
-   QQ 代理验证所有请求的代理密钥
-   \* 代理使用内部SUPERVISOR TOKEN进行家庭助理API操作
-   您的代理密钥只存储在本地的 IDE 配置文件中
-   ⚠️ **永远不要承诺 `mcp.json` 带着你的密钥特工来抓他!**

* * *

## 有关项目

-   **[HA 密码代理](https://github.com/Coolver/home-assistant-cursor-agent)** - 家庭助理(需要)
-   **[示范背景协议](https://modelcontextprotocol.io/)** - 议定书规格

* * *

## 许可证

麻省理工学院

* * *

## 发展

### 项目结构

```
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 密码代理** (单位:千美元)[https://github.com/Coolver/home-Assistant-vibecode-agent (英语)](https://github.com/Coolver/home-assistant-vibecode-agent)(REST API) 家庭助理整合

* * *

## 捐款

欢迎捐款! 请随意提交拉力请求.

1.  叉子存储器
2.  创建您的特性分支( E)`git checkout -b feature/AmazingFeature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add some AmazingFeature'`(中文(简体) )
4.  推向分行(`git push origin feature/AmazingFeature`(中文(简体) )
5.  打开拉请求

* * *

## ++ 辅助

-   🐛 **问题:** [GitHub 问题](https://github.com/Coolver/home-assistant-mcp/issues)
-   💡 **讨论:** [GitHub 讨论](https://github.com/Coolver/home-assistant-mcp/discussions)

* * *

## QQ 显示支持

如果这个项目能帮助你用AI控制你聪明的家,就给我一个!

## 常见问题

### @coolver/home-assistant-mcp 是什么？

启用 Cursor, VS 代码, Claude 代码或任何 MCP 启用的 IDE 来帮助您进行气相编码和管理家用助理: 创建自动化, 设计仪表板, 调整主题, 修改配置并使用自然语言部署更改

### 如何安装 @coolver/home-assistant-mcp？

在项目目录运行 npm install @coolver/home-assistant-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 home-assistant-mcp，可以用 npx home-assistant-mcp 直接运行。

### @coolver/home-assistant-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @coolver/home-assistant-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @coolver/home-assistant-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @coolver/home-assistant-mcp 可以商用吗？

@coolver/home-assistant-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @coolver/home-assistant-mcp 的下载量有多少？

根据 npm 官方下载统计，@coolver/home-assistant-mcp 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,547 次，日均约 85 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @coolver/home-assistant-mcp 还在维护吗？

最新版本 3\.2\.32 发布于 2026/10/22（20 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 34 个；首次发布于 2025/11/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。