homeassistant-light-mcp

🚀 Home Assistant Light MCP

Home Assistant Light MCP 是一个用于控制 Home Assistant 灯光并管理场景的模型上下文协议（MCP）服务器。它通过提供详细的灯光颜色控制和场景管理功能，对官方 Home Assistant MCP 进行了补充。

🚀 快速开始

本项目是用于控制 Home Assistant 灯光和管理场景的 MCP 服务器。若你想使用它，可按照以下步骤进行操作：

1. 安装项目（具体安装方式见“📦 安装指南”）。
2. 配置 MCP 客户端（具体配置方式见“📦 安装指南”）。
3. 参考“💻 使用示例”中的示例进行使用。

✨ 主要特性

• 展示灯光：查看所有灯光的详细信息，包括状态、亮度、RGB 颜色、色温、颜色模式、支持的模式、可用效果（如颜色循环等）以及色温范围（最小/最大开尔文）。
• 调节灯光：控制灯光的开关、亮度、RGB 颜色、色温以及效果。
• 创建场景：将当前灯光状态保存为场景，有两种模式可供选择：
  • exclusive：激活时关闭其他灯光。
  • additive：仅影响场景中的灯光。
• 列出场景：查看所有已保存的场景。
• 激活场景：激活已保存的场景（支持宜家 Tradfri 灯具）。
• 更新场景：使用当前灯光状态更新现有场景。
• 删除场景：移除场景。
• 全灭灯：关闭所有灯光（可选择排除部分灯光）。

📦 安装指南

使用 npm 全局安装

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 客户端

Claude Desktop

编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%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 的客户端。

获取 Home Assistant 令牌

1. 进入 Home Assistant → 个人资料（左下角）。
2. 滚动到“长期访问令牌”。
3. 点击“创建令牌”。
4. 复制令牌。

💻 使用示例

基础用法

展示灯光

"Show me all the lights"（显示所有灯光）

"What lights are on?"（哪些灯是亮着的？）

控制灯光

"Turn on living room light"（打开客厅灯）

"Set bedroom to 50% brightness"（将卧室灯光亮度设置为 50%）

"Make the kitchen light red"（将厨房灯设置为红色）

"Set studio lights to warm white"（将工作室灯光设置为暖白色）

"Start colorloop on the hallway light"（开启走廊灯的颜色循环效果）

创建场景

"Save this as Movie Night"（将此保存为“电影之夜”场景）

激活场景

"Activate Movie Night"（激活“电影之夜”场景）

更新场景

"Update Evening Lights with current settings"（用当前设置更新“晚间灯光”场景）

全灭灯

"Turn off all lights"（关闭所有灯光）

"Turn off all lights except the balcony"（关闭所有灯光，除了阳台灯）

📚 详细文档

工具参考

| 工具 | 描述 | |------|-------------| | scene_show_lights | 展示所有灯光的状态、亮度、颜色、效果和颜色模式等信息 | | scene_adjust_light | 控制灯光的开关、亮度、颜色和效果等 | | scene_create | 根据当前灯光状态创建新场景 | | scene_list | 列出所有场景 | | scene_activate | 激活场景 | | scene_update | 使用当前灯光状态更新现有场景 | | scene_delete | 删除场景 | | scene_blackout | 关闭所有灯光（支持排除部分灯光） | | scene_diagnose | 诊断灯光和场景，检查连接情况 | | scene_fix | 修复场景问题，从备份中恢复 | | scene_configure | 设置 Home Assistant 的 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 - 色温范围（最小/最大开尔文，如果支持）

场景模式

• Exclusive（独占模式）：关闭场景外的所有灯光，适用于特定房间的场景。
• Additive（叠加模式）：仅影响场景中的灯光，适用于重点照明。

本地备份与多实例支持

本 MCP 会对创建的场景进行本地备份：

• 自动备份：场景会保存到 ~/.config/ha-mcp-server/scenes-backup.json。
• 多实例感知：检测其他 MCP 实例（或 HA UI）对场景的修改。
• 智能冲突解决：合并多个来源的更改。
• 恢复功能：如果 Home Assistant 丢失场景，可从本地备份中恢复。

诊断功能（scene_diagnose）

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

• 测试灯光连接和响应时间。
• 检测连接类型（Zigbee、WiFi、蓝牙）。
• 查找包含空值或缺少灯光的场景。
• 比较 Home Assistant 状态和本地备份。
• 报告未包含在独占场景中的新灯光。

示例："Run diagnostics on my lights"（对我的灯光进行诊断）

修复功能（scene_fix）

有四种操作可用于修复场景问题： | 操作 | 描述 | |--------|-------------| | fix_all | 自动修复所有场景：移除空值，将缺失的灯光添加到独占场景中 | | fix_scene | 按名称修复特定场景 | | test_scene | 激活场景并报告出现的问题 | | restore_from_backup | 如果 Home Assistant 丢失场景，从本地备份中恢复 |

示例："Fix all my scenes"（修复我所有的场景）或 "Restore Evening Lights from backup"（从备份中恢复“晚间灯光”场景）

宜家 Tradfri 支持

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

注意：由于这些时序问题，Home Assistant 的原生场景与 Tradfri 灯具配合使用时不可靠。本 MCP 通过独立管理场景并设置适当的延迟来提供解决方案。

本 MCP 会自动处理 Tradfri 灯具：

• 通过制造商名称检测 Tradfri 设备。
• 在模式切换和后续命令之间添加 500ms 延迟。
• 正确排序颜色/温度更改和亮度调整。

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

安全说明

数据本地保存

• 所有通信都直接在你的计算机和 Home Assistant 实例之间进行。
• 不会将数据发送到外部服务器或第三方。
• MCP 服务器通过标准输入输出在本地机器上运行（无开放网络端口）。

无跟踪

我们不会对你进行跟踪。

令牌安全

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

服务器访问权限

• 仅可访问 Home Assistant 中的灯光和场景。
• 无法访问其他 Home Assistant 实体（传感器、锁、摄像头等）。
• 除了灯光控制和场景管理外，无法进行其他更改。

📄 许可证

本项目采用 MIT 许可证，你可以自由使用，建议保留原作者信息，但不做强制要求。

贡献说明

如果你发现了 bug 或有新的想法，欢迎 提交问题 或发起拉取请求！

作者

Koneisto

Built by people with questionable priorities （由一群优先级存疑的人开发）