使用说明

飞利浦Hue MCP服务器

一个强大的模型上下文协议（MCP）接口，用于控制飞利浦秀智能照明系统。让像克劳德这样的人工智能助手使用自然语言控制你的灯光。

概述

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

特性

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

快速开始

# Install dependencies using uv (recommended)
uv sync

# Test with MCP Inspector
uv run mcp dev hue_server.py

# Install in Claude Desktop
uv run mcp install hue_server.py --name "Philips Hue"

然后在克劳德，开始：“我想控制我的飞利浦秀灯。你能告诉我我有哪些灯吗？”

设置

先决条件

Python 3.10或更高版本
紫外线包管理器（推荐）
本地网络上的飞利浦秀网桥
飞利浦秀灯与您的桥接器搭配

安装

使用紫外线（推荐）：

# Clone the repository
git clone https://github.com/ThomasRohde/hue-mcp.git
cd hue-mcp

# Install dependencies and create virtual environment automatically
uv sync

# Activate the virtual environment (optional, uv run handles this automatically)
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

使用pip：

# Clone the repository
git clone https://github.com/ThomasRohde/hue-mcp.git
cd hue-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

首次运行

使用MCP检查器测试服务器：

uv run mcp dev hue_server.py

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

与克劳德一起使用

在Claude桌面中安装

将此服务器与Claude Desktop一起使用的最简单方法：

# Install with default name
uv run mcp install hue_server.py

# Or with custom name
uv run mcp install hue_server.py --name "Philips Hue Controller"

# With environment variables if needed
uv run mcp install hue_server.py --name "Hue" -v DEBUG=1

手动配置

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

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

窗户： %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

macOS：

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

窗户：

{
  "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检查员进行测试

对于开发和测试，请使用MCP检查器：

uv run mcp dev hue_server.py

# With additional dependencies
uv run mcp dev hue_server.py --with pandas

# With debug logging
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 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)

高级选项

命令行参数

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

# Run with stdio transport (default, for MCP clients)
python hue_server.py

# Run with custom host and port (HTTP/SSE mode)
python hue_server.py --sse --host 0.0.0.0 --port 8888

# Enable debug logging
python hue_server.py --log-level debug

# Show all available options
python hue_server.py --help

参数	描述	默认值
`--host`	将服务器绑定到的主机（仅限SSE模式）	`127.0.0.1`
`--port`	运行服务器的端口（仅限SSE模式）	`8080`
`--log-level`	日志记录级别（调试、信息、警告、错误、严重）	`info`
`--sse`	使用SSE传输而不是stdio运行服务器	`False`

发展模式

开发或测试时：

# Use MCP dev command for automatic reloading
uv run mcp dev hue_server.py --log-level debug

# Or run directly with uv (stdio is default)
uv run python hue_server.py --log-level debug

故障排除

未找到桥：如果自动发现不起作用，您有两个选择：
1. 手动编辑 BRIDGE_IP 脚本中的变量与网桥的IP地址
2. 手动创建配置文件：
```
# Create the config directory
mkdir -p ~/.hue-mcp

# Create a config.json file with your bridge IP
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系统的所有通信都在您的网络内本地进行。

贡献

我们热衷于支持各级经验的贡献者，并希望看到您参与该项目。看贡献指南开始吧。

项目结构

hue-mcp/
├── hue_server.py       # Main MCP server implementation
├── pyproject.toml      # Project configuration and dependencies
├── README.md           # This file
├── CONTRIBUTING.md     # Contribution guidelines
├── CHANGELOG.md        # Version history
├── LICENSE             # MIT License
├── tests/              # Test suite
│   ├── __init__.py
│   └── test_hue_server.py
└── .venv/              # Virtual environment (created during setup)

发展

# Install development dependencies
uv sync

# Run tests
uv run pytest

# Format code
uv run ruff check --fix hue_server.py

# Type check
uv run mypy hue_server.py

# Test with MCP Inspector
uv run mcp dev hue_server.py --log-level debug

许可证

该项目在MIT许可下可用。看许可证了解详情。