Philips Hue MCP 服务器

一个强大的模型上下文协议（MCP）接口，用于控制飞利浦 Hue 智能照明系统。使像 Claude 这样的AI助手能够通过自然语言来控制你的灯光。

目录

• Philips Hue MCP 服务器
  • 目录
  • 概述
  • 特性
  • 快速开始
  • 设置
    • 先决条件
    • 安装
    • 首次运行
  • 与 Claude 配合使用
    • 在 Claude Desktop 中安装
    • 手动配置
    • 使用 MCP Inspector 测试
  • API 参考
    • 资源
    • 工具
    • 提示
  • 示例
    • 控制单个灯
    • 处理组
    • 创建场景
  • 高级选项
    • 命令行参数
    • 开发模式
  • 故障排除
  • 工作原理
  • 贡献
    • 项目结构
    • 开发
  • 许可证

概述

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

特性

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

快速开始

# 使用 uv 安装依赖项（推荐）
uv sync

# 使用 MCP Inspector 测试
uv run mcp dev hue_server.py

# 在 Claude Desktop 中安装
uv run mcp install hue_server.py --name "Philips Hue"

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

设置

先决条件

• Python 3.10 或更高版本
• uv 包管理器（推荐）
• 本地网络上的飞利浦 Hue 桥接器
• 已配对到桥接器的飞利浦 Hue 灯

安装

使用 uv（推荐）：

# 克隆仓库
git clone https://github.com/ThomasRohde/hue-mcp.git
cd hue-mcp

# 安装依赖项并自动创建虚拟环境
uv sync

# 激活虚拟环境（可选，uv run 自动处理）
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

使用 pip：

# 克隆仓库
git clone https://github.com/ThomasRohde/hue-mcp.git
cd hue-mcp

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖项
pip install -e ".[dev]"

首次运行

1. 使用 MCP Inspector 测试服务器：

uv run mcp dev hue_server.py

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

与 Claude 配合使用

在 Claude Desktop 中安装

最简单的方法是使用此服务器与 Claude Desktop 配合：

# 使用默认名称安装
uv run mcp install hue_server.py

# 或使用自定义名称
uv run mcp install hue_server.py --name "Philips Hue 控制器"

# 如需环境变量
uv run mcp install hue_server.py --name "Hue" -v DEBUG=1

手动配置

或者，您可以通过编辑配置文件来手动配置 Claude Desktop：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

macOS:

{
  "mcpServers": {
    "hue": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/username/Projects/hue-mcp",
        "run",
        "hue_server.py"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "hue": {
      "command": "uv",
      "args": [
        "--directory",
        "c:\\Users\\username\\Projects\\hue-mcp",
        "run",
        "hue_server.py"
      ]
    }
  }
}

将 /Users/username/Projects/hue-mcp（macOS）或 c:\\Users\\username\\Projects\\hue-mcp（Windows）替换为您克隆的仓库的实际路径。--directory 标志确保 uv 在正确的项目目录中运行，并能找到 pyproject.toml 中定义的依赖项。

更新配置后，请重启 Claude Desktop 以使更改生效。

使用 MCP Inspector 测试

对于开发和测试，使用 MCP Inspector：

uv run mcp dev hue_server.py

# 带有额外依赖项
uv run mcp dev hue_server.py --with pandas

# 带有调试日志
uv run mcp dev hue_server.py --log-level debug

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("卧室", [3, 4, 5])

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

创建场景

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

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

高级选项

命令行参数

当直接运行服务器时，支持以下命令行参数：

# 使用 stdio 传输（默认，适用于 MCP 客户端）
python hue_server.py

# 使用自定义主机和端口（HTTP/SSE 模式）
python hue_server.py --sse --host 0.0.0.0 --port 8888

# 启用调试日志
python hue_server.py --log-level debug

# 显示所有可用选项
python hue_server.py --help

参数	描述	默认值
--host	绑定服务器的主机（仅限 SSE 模式）	127.0.0.1
--port	运行服务器的端口（仅限 SSE 模式）	8080
--log-level	日志级别（debug, info, warning, error, critical）	info
--sse	使用 SSE 传输而不是 stdio 运行服务器	False

开发模式

在开发或测试时：

# 使用 MCP dev 命令进行自动重新加载
uv run mcp dev hue_server.py --log-level debug

# 或直接使用 uv 运行（stdio 是默认的）
uv run python hue_server.py --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 库连接到您的飞利浦 Hue 桥接器，并通过模型上下文协议暴露功能。当像 Claude 这样的AI连接时：

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

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

贡献

我们热衷于支持各种经验水平的贡献者，并希望看到您参与这个项目。参阅 贡献指南 开始。

项目结构

hue-mcp/
├── hue_server.py       # 主 MCP 服务器实现
├── pyproject.toml      # 项目配置和依赖项
├── README.md           # 此文件
├── CONTRIBUTING.md     # 贡献指南
├── CHANGELOG.md        # 版本历史
├── LICENSE             # MIT 许可证
├── tests/              # 测试套件
│   ├── __init__.py
│   └── test_hue_server.py
└── .venv/              # 虚拟环境（设置期间创建）

开发

# 安装开发依赖项
uv sync

# 运行测试
uv run pytest

# 格式化代码
uv run ruff check --fix hue_server.py

# 类型检查
uv run mypy hue_server.py

# 使用 MCP Inspector 测试
uv run mcp dev hue_server.py --log-level debug

许可证

此项目在 MIT 许可证下提供。详情见 LICENSE。