Philips Hue MCP 服务器

一个强大的模型上下文协议 (MCP) 接口，用于控制 Philips Hue 智能照明系统。

目录

• Philips Hue MCP 服务器
  • 概述
  • 特性
  • 快速开始
  • 设置
    • 先决条件
    • 安装
    • 首次运行
  • 与 Claude 一起使用
  • API 参考
    • 资源
    • 工具
    • 提示
  • 示例
    • 控制单个灯
    • 使用群组
    • 创建场景
  • 高级选项
  • 故障排除
  • 工作原理
  • 贡献
  • 许可证

概述

此服务器利用模型上下文协议 (MCP) 在 AI 助手（如 Claude）和您的 Philips Hue 照明系统之间提供无缝集成。 通过它，您可以使用自然语言控制智能灯，访问详细的照明信息，并通过标准化的 AI 友好界面创建高级照明设置。

特性

• 完整的灯光控制：打开/关闭、调节亮度、更改颜色、设置色温
• 全面的群组管理：一起控制多个灯，创建自定义群组
• 场景处理：应用现有场景，创建快速自定义照明场景
• 基于活动的预设：用于阅读、放松、集中注意力等的现成设置
• 特殊效果：访问动态照明效果，如颜色循环
• 自然语言控制：用于通过对话进行灯光控制的专用提示
• 安全的本地集成：直接连接到本地网络上的 Hue 桥接器

快速开始

# 安装依赖
pip install phue mcp

# 运行服务器
python hue_server.py

# 在 Claude Desktop 中安装
mcp install hue_server.py --name "My Hue Lights"

然后在 Claude 中，从以下内容开始：“我想控制我的 Philips Hue 灯。你能告诉我有哪些灯可用吗？”

设置

先决条件

• Python 3.9+
• 本地网络上的 Philips Hue 桥接器
• 与桥接器配对的 Philips Hue 灯

安装

1. 克隆此存储库或下载 hue_server.py 文件
2. 安装所需的依赖项：

pip install phue mcp

首次运行

1. 运行服务器：

python hue_server.py

2. 出现提示时，按下 Hue 桥接器上的链接按钮以授权连接
3. 您的连接详细信息将保存在 ~/.hue-mcp/config.json 中以供将来使用

与 Claude 一起使用

选项 1：在 Claude Desktop 中安装

如果您已安装 Claude Desktop：

mcp install hue_server.py --name "Philips Hue Controller"

选项 2：使用 MCP Inspector 进行测试

用于开发和测试：

mcp dev hue_server.py

API 参考

资源

资源	描述
hue://lights	关于所有灯的信息
hue://lights/{light_id}	关于特定灯的详细信息
hue://groups	关于所有灯组的信息
hue://groups/{group_id}	关于特定群组的信息
hue://scenes	关于所有场景的信息

工具

工具	描述
get_all_lights	获取关于所有灯的信息
get_light	获取关于特定灯的详细信息
get_all_groups	获取关于所有灯组的信息
get_group	获取关于特定群组的信息
get_all_scenes	获取关于所有场景的信息
turn_on_light	打开特定灯
turn_off_light	关闭特定灯
set_brightness	调节灯亮度 (0-254)
set_color_rgb	使用 RGB 值设置灯颜色
set_color_temperature	设置灯色温 (2000-6500K)
turn_on_group	打开群组中的所有灯
turn_off_group	关闭群组中的所有灯
set_group_brightness	调节群组亮度 (0-254)
set_group_color_rgb	设置群组中所有灯的颜色
set_scene	将场景应用于群组
find_light_by_name	按名称搜索灯
create_group	创建新的灯组
quick_scene	应用自定义设置以创建场景
refresh_lights	更新灯信息缓存
set_color_preset	将颜色预设应用于灯
set_group_color_preset	将颜色预设应用于群组
alert_light	使灯短暂闪烁
set_light_effect	设置动态效果，如颜色循环

提示

提示	描述
control_lights	自然语言灯光控制
create_mood	为活动设置情境照明
light_schedule	了解调度选项

示例

控制单个灯

# 打开一个灯
turn_on_light(1)

# 将灯设置为 50% 亮度
set_brightness(1, 127)

# 将灯的颜色更改为紫色
set_color_rgb(1, 128, 0, 128)

# 设置阅读模式
set_color_preset(1, "reading")

使用群组

# 关闭客厅中的所有灯（群组 2）
turn_off_group(2)

# 创建一个新群组
create_group("Bedroom", [3, 4, 5])

# 将所有厨房灯设置为活力模式
set_group_color_preset(3, "energize")

创建场景

# 应用现有场景
set_scene(2, "abc123")  # 群组 2，场景 ID abc123

# 为客厅创建一个快速放松的场景
quick_scene("Evening Relaxation", group_id=2, rgb=[255, 147, 41], brightness=120)

高级选项

使用自定义设置运行服务器：

python hue_server.py --host 0.0.0.0 --port 8888 --log-level debug

故障排除

• 未找到桥接器：如果自动发现不起作用，您有两个选择：

  1. 手动编辑脚本中的 BRIDGE_IP 变量，使用您的桥接器的 IP 地址
  2. 手动创建一个配置文件：

     # 创建配置目录
     mkdir -p ~/.hue-mcp
     
     # 创建一个包含您的桥接器 IP 的 config.json 文件
     echo '{"bridge_ip": "192.168.1.x"}' > ~/.hue-mcp/config.json
     

     将 "192.168.1.x" 替换为您的实际 Hue 桥接器 IP 地址

• 连接问题：删除 ~/.hue-mcp/config.json 并重新启动服务器以重新验证

• 灯光控制不起作用：使用 refresh_lights 工具更新灯光信息缓存

• 群组或场景未显示：重新启动桥接器和服务器以同步所有数据

工作原理

此服务器使用 phue Python 库连接到您的 Philips Hue 桥接器，并通过模型上下文协议公开功能。 当像 Claude 这样的 AI 连接时：

1. 服务器使用存储的凭据向您的桥接器进行身份验证
2. 它提供描述您的照明设置的资源
3. 它公开 Claude 可以用来控制您的灯的工具
4. 它提供提示，帮助 Claude 了解如何与您的灯互动

与您的 Hue 系统的所有通信都在您的网络本地进行，以确保安全和隐私。

贡献

欢迎贡献！ 随意：

• 在问题跟踪器中报告错误并提出功能建议
• 提交包含改进的拉取请求
• 分享您如何将此与您的智能家居设置一起使用的示例

许可证

本项目在 MIT 许可证下可用。