Home Assistant Light MCP

家居助理灯MCP

](https://www.npmjs.com/package/ha-mcp-server)  

用于控制家庭助理灯和管理场景的模型上下文协议（MCP）服务器。通过提供详细的灯光控制、颜色和场景管理来补充官方的家庭助理MCP。

像这个项目？ 给它一个⭐ 在GitHub上，帮助他人发现它！

设计理念：仅限灯光

此MCP 故意只控制灯光 -不是交换机，不是其他实体。这是一个深思熟虑的安全决策：

• 交换机可以控制关键系统 -暖通空调、加热器、空调、水泵
• 意外激活可能存在危险 -外出时打开加热器，夏天禁用空调
• 灯是安全的 -最坏的情况是灯意外打开/关闭

如果您需要控制交换机或其他实体，请使用官方的家庭助理MCP或具有适当保护措施的自动化系统。

特性

• 显示灯光 -查看所有灯光的完整细节：

- 状态、亮度、RGB颜色、色温 - 颜色模式和支持的模式 - 可用效果（颜色循环等） - 色温范围（最小/最大开尔文）

• 调整灯光 -控制灯光（开/关、亮度、RGB颜色、色温、效果）
• 创建场景 -使用两种模式将当前照明保存为场景：

- exclusive -激活时关闭其他灯 - additive -仅影响场景中的灯光

• 列出场景 -查看所有已保存的场景
• 激活场景 -激活已保存的场景（使用IKEA Tradfri支持）
• 更新场景 -使用当前灯光状态更新现有场景
• 删除场景 -删除场景
• 停电 -关闭所有灯（可选除外）

为什么选择MCP？

官方的家庭助理MCP是有限的-它不能显示浅色或提供详细的状态信息。此MCP填补了这一空白：

安装

npm install -g ha-mcp-server

或者克隆并构建：

git clone https://github.com/Koneisto/HomeAssistant-Light-MCP.git
cd HomeAssistant-Light-MCP
npm install
npm run build

配置

添加到MCP客户端配置中：

克劳德桌面版

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

选项1：使用npx（推荐，不需要全局安装）

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "npx",
      "args": ["-y", "ha-mcp-server"],
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

选项2：全局安装

npm install -g ha-mcp-server

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "ha-mcp-server",
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

其他MCP客户端

相同的配置结构适用于任何兼容MCP的客户端。

获取您的家庭助理令牌

1. 转到家庭助理→ 剖面图（左下）
2. 滚动到“长期访问令牌”
3. 点击“创建令牌”
4. 复制令牌

使用示例

显示灯光

“让我看看所有的灯”

“什么灯亮着？”

控制灯

“打开客厅灯”

“将卧室亮度设置为50%”

“把厨房变成红色”

“将工作室灯光设置为暖白色”

“走廊灯开始变色”

创建场景

“将此保存为电影之夜”

激活场景

“激活电影之夜”

更新场景

“使用当前设置更新夜灯”

停电

“关闭所有灯”

“关闭除阳台外的所有灯”

工具参考

灯光属性

scene_show_lights 返回：

• state -开/关
• brightness / brightness_pct - 0-255 / 0-100%
• rgb_color -\[R、G、B\]值
• color_temp_kelvin -色温
• color_mode -当前模式（xy、color_temp、rgb、hs）
• supported_color_modes -光支持什么
• effect -主动效果（如有）
• effect_list -可用效果
• color_temp_range -最小/最大开尔文（如果支持）

场景模式

• 独家：关闭不在场景中的所有灯光。适用于特定房间的场景。
• 添加剂：仅影响场景中的灯光。适合重点照明。

本地备份和多实例支持

此MCP维护您创建的场景的本地备份：

• 自动备份：场景保存到 ~/.config/ha-mcp-server/scenes-backup.json
• 多实例感知：检测另一个MCP实例（或HA UI）何时修改场景
• 智能冲突解决：合并来自多个来源的更改
• 恢复能力：如果家庭助理丢失场景，可以恢复它们

诊断(scene_diagnose)

分析灯光和场景以识别问题：

• 测试光连接和响应时间
• 检测连接类型（Zigbee、WiFi、蓝牙）
• 查找具有空值或缺少灯光的场景
• 将家庭助理状态与本地备份进行比较
• 报告独家场景中尚未出现新灯光

例子： *“对我的灯运行诊断”*

修复与修理(scene_fix)

修复场景问题的四个操作：

例子： *“修复我所有的场景”* 或 *“从备份中恢复夜灯”*

宜家Tradfri支持

宜家Tradfri灯在RGB颜色模式和色温（开尔文）模式之间切换时存在已知问题。灯泡在接受亮度或颜色值之前需要时间来处理模式更改。

注： 由于这些时间问题，Home Assistant的原生场景无法与Tradfri灯可靠地配合使用。此MCP通过以适当的延迟独立管理场景提供了一种解决方法。

此MCP通过以下方式自动处理Tradfri灯：

• 按制造商名称检测Tradfri设备
• 在模式切换和后续命令之间增加500毫秒的延迟
• 通过亮度调节正确排序颜色/温度变化

如果没有这些修复，Tradfri灯在切换模式时经常忽略命令或产生不正确的颜色。

安全

您的数据保留在本地

• 所有通信都直接发生在您的计算机和家庭助理实例之间
• 不向外部服务器或第三方发送数据
• MCP服务器通过stdio在您的计算机上本地运行（没有开放的网络端口）

无跟踪

• 我们不太关心你的行踪

令牌安全

• 您的家庭助理令牌仅存储在本地计算机上
• 使用环境变量避免将令牌存储在文件中
• 令牌仅发送到您自己的Home Assistant实例
• 您可以随时从家庭助理设置中撤销令牌

此服务器可以访问什么

• 仅在家庭助理中显示灯光和场景
• 无法访问其他家庭助理实体（传感器、锁、摄像头等）
• 无法在灯光控制和场景管理之外进行更改

贡献

发现bug还是有想法？ 打开一个问题 或者提交一个pull请求！

许可证

麻省理工学院-自由使用，感谢归因，但不是必需的。

作者

Koneisto

______________________________________________________________________

*由优先级有问题的人建造*