HomeAssistant-Light-MCP

Name: HomeAssistant-Light-MCP
Author: Koneisto

本地服务

github.com/Koneisto其他039 周前更新

代码仓库

关于 HomeAssistant-Light-MCP

Home Assistant 的 MCP 服务，用于查看和控制灯光以及管理场景，适合希望通过 MCP 客户端操作照明的用户。它刻意限制在灯光和场景范围内，不控制开关或其他实体。

主要功能

01查看灯光状态、亮度和颜色
02调整开关、亮度、色彩与效果
03创建、查看、更新和删除场景
04激活场景及关闭全部灯光
05诊断并修复场景问题

适用场景

01通过 MCP 客户端调整房间灯光
02保存并切换照明场景
03检查并恢复丢失的场景
04排查灯光连接或场景异常

MCP 相关

通过 MCP 工具向客户端开放 Home Assistant 的灯光控制和场景管理能力。服务仅操作灯光与场景，并通过 stdio 在本机运行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "koneisto-homeassistant-light": {
      "command": "npx",
      "args": [
        "-y",
        "ha-mcp-server"
      ],
      "env": {
        "HA_URL": "<HA_URL>",
        "HA_TOKEN": "<HA_TOKEN>"
      }
    }
  }
}

启动命令npx -y ha-mcp-server

需要配置的环境变量

HA_URLHome Assistant URL (e.g., http://192.168.1.100:8123)

HA_TOKEN密钥Home Assistant long-lived access token

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmha-mcp-server0.6.1stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
url	string	是	Home Assistant URL（例如，'http://192.168.1.100:8123'）
token	string	是	Home Assistant 的长期访问令牌

详细介绍

Home Assistant Light MCP

一个用于控制 Home Assistant 灯具和管理场景的模型上下文协议（MCP）服务。它与官方 Home Assistant MCP 互为补充，可提供详细的灯光控制功能，包括颜色和场景管理。

喜欢这个项目？ 在 GitHub 上点个 ⭐，帮助更多人发现它！

设计理念：仅控制灯具

此 MCP 有意仅控制灯具，不控制开关或其他实体。这是出于安全考虑的决定：

开关可能控制关键系统——暖通空调、加热器、空调、水泵
意外启动可能很危险——外出时打开加热器，或在夏天关闭空调
灯具是安全的——最坏的情况也只是灯意外打开或关闭

如果需要控制开关或其他实体，请使用官方 Home Assistant MCP，或设置带有适当安全措施的自动化。

功能

显示灯具——查看所有灯具的详细信息：
- 状态、亮度、RGB 颜色、色温
- 颜色模式和支持的模式
- 可用效果（colorloop 等）
- 色温范围（最小/最大开尔文值）
调整灯光——控制灯光（开/关、亮度、RGB 颜色、色温、效果）
创建场景——将当前灯光设置保存为场景，支持两种模式：
- exclusive——激活时关闭其他灯具
- additive——仅影响场景中的灯具
列出场景——查看所有已保存的场景
激活场景——激活已保存的场景（支持 IKEA Tradfri）
更新场景——使用当前灯光状态更新现有场景
删除场景——移除场景
全屋熄灯——关闭所有灯具（可选择排除项）

为什么选择此 MCP？

官方 Home Assistant MCP 功能有限——它无法显示灯光颜色，也无法提供详细的状态信息。此 MCP 弥补了这些不足：

功能	官方 HA MCP	此 MCP
显示灯光颜色	否	是
显示亮度	有限	完整详情
显示颜色模式	否	是
显示效果	否	是
设置 RGB 颜色	否	是
色温	否	是
设置效果	否	是
创建场景	否	是
IKEA 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 客户端：

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 令牌

前往 Home Assistant → 个人资料（左下角）
向下滚动到“长期访问令牌”
点击“创建令牌”
复制令牌

使用示例

显示灯具

“显示所有灯具”

“哪些灯开着？”

控制灯光

“打开客厅的灯”

“将卧室亮度设为 50%”

“把厨房的灯调成红色”

“把工作室的灯调成暖白色”

“启动走廊灯的 colorloop 效果”

创建场景

“将当前设置保存为 Movie Night”

激活场景

“激活 Movie Night”

更新场景

“使用当前设置更新 Evening Lights”

全屋熄灯

“关闭所有灯”

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

工具参考

工具	描述
`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 - 最低/最高开尔文值（如果支持）

场景模式

独占：关闭场景中未包含的所有灯。适用于房间专属场景。
叠加：仅影响场景中的灯。适用于重点照明。

本地备份和多实例支持

此 MCP 会在本地备份你创建的场景：

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

诊断（`scene_diagnose`）

分析灯和场景以找出问题：

测试灯的连接情况和响应时间
检测连接类型（Zigbee、WiFi、Bluetooth）
查找值为 null 或缺少灯的场景
对比 Home Assistant 状态与本地备份
报告尚未添加到独占场景的新灯

示例：“诊断我的灯”

修复（`scene_fix`）

提供四种操作来修复场景问题：

操作	描述
`fix_all`	自动修复所有场景：移除 null 值，将缺失的灯添加到独占场景
`fix_scene`	按名称修复指定场景
`test_scene`	激活场景并报告问题
`restore_from_backup`	如果 Home Assistant 丢失场景，则从本地备份恢复

示例：“修复我的所有场景” 或 “从备份恢复 Evening Lights”

IKEA Tradfri 支持

IKEA Tradfri 灯在 RGB 颜色模式和色温（开尔文）模式之间切换时存在已知问题。灯泡需要时间处理模式切换，然后才能接收亮度或颜色值。

**注意：**由于这些时序问题，Home Assistant 原生场景无法可靠地用于 Tradfri 灯。此 MCP 通过独立管理场景并设置适当的延迟来提供变通方案。

此 MCP 会自动处理 Tradfri 灯，方法包括：

根据制造商名称检测 Tradfri 设备
在模式切换和后续命令之间增加 500ms 延迟
正确安排颜色/色温更改与亮度调整的顺序

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

安全

你的数据留在本地

所有通信都直接发生在你的计算机与 Home Assistant 实例之间
不会向外部服务或第三方发送任何数据
MCP 服务通过 stdio 在你的机器上本地运行（不开放网络端口）

不追踪

我们不至于在乎到要追踪你

令牌安全

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

此服务可以访问的内容

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

贡献

发现了错误或有想法？提交 issue 或提交 pull request！

许可证

MIT——可自由使用，建议注明出处，但不作要求。

作者

Koneisto

由一群优先事项颇为可疑的人打造

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。