AI导哈

智能灯光控制服务器

一个用于控制Home Assistant灯光和管理场景的模型上下文协议(MCP)服务器，提供详细的灯光控制和场景管理功能。

  • by Koneisto
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Koneisto/HomeAssistant-Light-MCP

使用说明

家居助理灯MCP

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

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

设计理念：仅限灯光

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

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

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

特性

  • 显示灯光 -查看所有灯光的完整细节：
    • 状态、亮度、RGB颜色、色温
    • 颜色模式和支持的模式
    • 可用效果（颜色循环等）
    • 色温范围（最小/最大开尔文）
  • 调整灯光 -控制灯光（开/关、亮度、RGB颜色、色温、效果）
  • 创建场景 -使用两种模式将当前照明保存为场景：
    • exclusive -激活时关闭其他灯
    • additive -仅影响场景中的灯光
  • 列出场景 -查看所有已保存的场景
  • 激活场景 -激活已保存的场景（使用IKEA Tradfri支持）
  • 更新场景 -使用当前灯光状态更新现有场景
  • 删除场景 -删除场景
  • 停电 -关闭所有灯（可选除外）

为什么选择MCP？

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

功能 官方HA MCP 此MCP
显示浅色 否 是
显示亮度 有限 完整细节
显示颜色模式 否 是
显示效果 否 是
设置RGB颜色 否 是
色温 否 是
设置效果 否 是
创建场景 否 是
宜家Tradfri修复 否 是

安装

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 显示所有灯的状态、亮度、颜色、效果、颜色模式
scene_adjust_light 控制灯光（开/关、亮度、颜色、效果）
scene_create 从当前灯光状态创建新场景
scene_list 列出所有场景
scene_activate 激活场景
scene_update 使用当前灯光更新现有场景
scene_delete 删除场景
scene_blackout 关闭所有灯（支持排除）
scene_diagnose 诊断灯光和场景，检查连接
scene_fix 修复场景问题，从备份还原
scene_configure 设置家庭助理URL和令牌

灯光属性

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)

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

动作 描述
fix_all 自动修复所有场景：删除空值，将缺失的灯光添加到独占场景中
fix_scene 按名称修复特定场景
test_scene 激活一个场景并报告出了什么问题
restore_from_backup 如果家庭助理丢失了场景，请从本地备份中还原它们

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

宜家Tradfri支持

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

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

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

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

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

安全

您的数据保留在本地

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

无跟踪

  • 我们不太关心你的行踪

令牌安全

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

此服务器可以访问什么

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

贡献

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

许可证

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

作者

Koneisto

由优先级有问题的人建造

相关 MCP