Hue MCP Server

Hue MCP服务器

模型上下文协议（MCP）服务器，用于通过Claude等人工智能助手控制飞利浦秀照明系统。

特性

• 多桥支撑：同时控制多个色调桥接器
• 实时同步：基于SSE的同步实时更新状态
• 缓存响应：通过智能缓存层即时响应
• 综合工具：控制灯光、房间、场景和桥梁
• 智能提示：人工智能辅助照明建议和场景创建
• 资源：接入网桥状态和设备清单

建筑

Claude Desktop / AI Client
    ↓ (MCP Protocol)
MCP Server (hue-mcp)
    ↓
Cache Layer (hue-cache)
    ↓
Base SDK (hue-sdk)
    ↓
Hue Bridge Pro(s)

安装

先决条件

• 转到1.25.6或更高版本
• 飞利浦Hue Bridge Pro，可访问API
• 网桥IP地址和应用密钥

建筑

cd /tmp/hue-mcp
go build -o hue-mcp main.go

配置

服务器在中查找配置 ~/.config/hue-mcp/config.json （或 $XDG_CONFIG_HOME/hue-mcp/config.json).

配置文件结构

{
  "bridges": [
    {
      "id": "bridge-1",
      "name": "Main Bridge",
      "ip": "192.168.1.100",
      "app_key": "your-app-key-here",
      "enabled": true
    }
  ],
  "cache": {
    "type": "file",
    "file_path": "~/.cache/hue-mcp/bridges",
    "auto_save_interval": 30,
    "warm_on_startup": true
  },
  "server": {
    "log_level": "info"
  }
}

获取应用程序密钥

如果您没有应用程序密钥，可以使用Hue SDK生成一个：

// TODO: Add setup wizard tool or link to hue-sdk documentation

Claude桌面集成

将以下内容添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "hue": {
      "command": "/tmp/hue-mcp/hue-mcp",
      "args": []
    }
  }
}

重新启动Claude Desktop以加载MCP服务器。

可用工具

设置和发现

• discover_bridges -在您的网络上查找Hue网桥（通过discovery.meethe.com查找N-UPnP）
• authenticate_bridge -使用网桥进行身份验证（需要按下链接按钮）
• add_bridge -将经过身份验证的网桥添加到配置中
• remove_bridge -从配置中删除网桥
• get_config_path -获取配置文件位置

桥梁管理

• list_bridges -列出所有已配置的Hue网桥
• get_bridge_info -获取详细的桥梁信息

灯光控制

• list_lights -列出桥梁上的所有灯光
• get_light -获取详细的灯光信息
• control_light -全面的单灯控制：

- 开/关，亮度（0-100%） - 通过XY坐标显示RGB颜色 - 色温（白色光谱，153-500米汞柱） - 效果（蜡烛、火、棱镜、闪光、蛋白石、闪光、水下、宇宙、阳光、魔法） - 定时效果（日出、日落和持续时间） - 警报效果（呼吸） - 灯带渐变支撑

• control_lights -在一次通话中控制多个灯：

- 每盏灯都可以有独特的颜色、亮度和效果 - 非常适合：“将房间设置为彩虹”或“不同深浅的蓝色”

客房管理

• list_rooms -列出所有房间
• get_room -获取详细的房间信息

分组灯光控制

• list_grouped_lights -列出所有分组灯（房间和区域）
• get_grouped_light -获取组合灯的详细信息
• control_room_lights -同时控制房间/区域中的所有灯光：

- 单个API调用控制具有相同设置的所有灯光 - 开/关、亮度、RGB颜色、色温、警报 - 非常适合：“关闭所有卧室灯”或“将客厅设置为暖白色”

场景管理

• list_scenes -列出所有场景
• get_scene -获取详细的场景信息
• activate_scene -激活（回忆）场景：

- 可选亮度超控（0-100%） - 可选转换持续时间（0-6000000ms） - 将场景的照明配置应用于所有灯光

缓存管理

• warm_cache -手动填充/刷新缓存以实现即时访问
• cache_stats -查看缓存统计信息（命中率、条目、SSE同步状态）

可用资源

资源提供对网桥数据的只读访问：

• bridges://status -所有已配置网桥的状态
• bridges://devices -完整的设备清单
• bridges://rooms -所有房间横跨桥梁
• bridges://scenes -桥上的所有场景

可用提示

提示提供人工智能辅助交互：

• smart-lighting -根据活动获取照明建议
• create-scene -交互式场景创建助手
• energy-insights -能源使用分析和优化

示例用法

连接到Claude Desktop后，您可以自然地与灯光交互：

You: Turn on the living room lights
Claude: [Uses control_light tool to turn on lights]

You: What lights are currently on?
Claude: [Uses list_lights tool to check status]

You: Set the bedroom lights to a warm sunset color at 30% brightness
Claude: [Uses control_light with XY color coordinates]

You: Make the office lights a rainbow of colors
Claude: [Uses control_lights to set each light to different colors in one call]

You: Create a relaxing scene for the bedroom
Claude: [Uses create-scene prompt and tools to create scene]

缓存配置

缓存层提供：

• 文件后端：跨重启的持久缓存
• 自动保存：每30秒自动缓存持久化
• 开机预热：预加载缓存以实现即时首次访问
• SSE同步：通过服务器发送事件从网桥实时更新

缓存文件存储在 ~/.cache/hue-mcp/ 默认情况下。

发展

项目结构

/tmp/hue-mcp/
├── main.go                 # MCP server entry point
├── go.mod                  # Go module dependencies
├── pkg/
│   ├── bridge/
│   │   └── manager.go      # Bridge manager with cache integration
│   ├── config/
│   │   └── config.go       # Configuration management
│   └── tools/
│       ├── tools.go        # Tool registration
│       ├── setup.go        # Bridge discovery and setup tools
│       ├── bridges.go      # Bridge management tools
│       ├── lights.go       # Single light control tools
│       ├── lights_bulk.go  # Multi-light control tools
│       ├── rooms.go        # Room management tools
│       ├── scenes.go       # Scene management tools
│       └── cache.go        # Cache management tools

依赖项

• github.com/mark3labs/mcp-go -MCP SDK for Go
• github.com/rmrfslashbin/hue-sdk -基本色调API SDK
• github.com/rmrfslashbin/hue-cache -带SSE同步的缓存层

故障排除

桥梁连接问题

1. 验证网桥IP地址是否正确
2. 确保应用程序密钥有效
3. 检查网桥的网络连接
4. 查看登录 ~/.config/hue-mcp/logs/

缓存问题

1. 删除缓存文件： rm -rf ~/.cache/hue-mcp/
2. 重新启动MCP服务器
3. 验证SSE端点是否可访问

克劳德桌面未检测到服务器

1. 验证服务器构建成功： go build -o hue-mcp main.go
2. 检查中的配置路径 claude_desktop_config.json
3. 配置更改后重新启动Claude Desktop
4. 检查Claude Desktop开发人员控制台是否有错误

许可证

\[添加许可证信息\]

贡献

\[添加捐款指南\]

相关项目

• 色调sdk -飞利浦Hue API基础SDK
• 色调缓存 -具有SSE同步的缓存层