Philips Hue MCP 服务器

一个强大的模型上下文协议（MCP）接口，用于控制飞利浦 Hue 智能照明系统。

目录

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

概述

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

功能

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

快速开始

# Install dependencies
pip install phue mcp

# Run the server
python hue_server.py

# Install in Claude Desktop
mcp install hue_server.py --name "My Hue Lights"

然后在 Claude 中开始：“我想控制我的飞利浦 Hue 灯光。你能告诉我有哪些可用的灯吗？”

设置

前提条件

• Python 3.9+
• 本地网络中的飞利浦 Hue 桥接器
• 与桥接器配对的飞利浦 Hue 灯

安装

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

pip install phue mcp

首次运行

1. 运行服务器：

python hue_server.py

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

与 Claude 一起使用

选项 1：在 Claude 桌面中安装

如果您已安装 Claude 桌面：

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

选项 2：使用 MCP 检查器测试

用于开发和测试：

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 a light
turn_on_light(1)

# Set a light to 50% brightness
set_brightness(1, 127)

# Change a light color to purple
set_color_rgb(1, 128, 0, 128)

# Set reading mode
set_color_preset(1, "reading")

处理组

# Turn off all lights in living room (group 2)
turn_off_group(2)

# Create a new group
create_group("Bedroom", [3, 4, 5])

# Set all kitchen lights to energizing mode
set_group_color_preset(3, "energize")

创建场景

# Apply an existing scene
set_scene(2, "abc123")  # Group 2, scene ID abc123

# Create a quick relaxing scene for the living room
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 桥接器，并通过 Model Context Protocol 提供功能。当像 Claude 这样的 AI 连接时：

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

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

贡献

欢迎贡献！请随意：

• 在问题跟踪器中报告错误并建议功能
• 提交带有改进的拉取请求
• 分享您如何将此项目与智能家居设置结合使用的示例

许可证

此项目遵循 MIT 许可证。