Hue MCP Server

# Hue MCP Server A Model Context Protocol (MCP) server for controlling Philips Hue lighting systems through AI assistants like Claude. ## Features - **Multi-Bridge Support**: Control multiple Hue bridges simultaneously - **Real-Time Sync**: SSE-based synchronization keeps state updated in real-time - **Cached Responses**: Instant responses through intelligent caching layer - **Comprehensive Tools**: Control lights, rooms, scenes, and bridges - **Smart Prompts**: AI-assisted lighting suggestions and scene creation - **Resources**: Access bridge status and device inventory ## Architecture ``` Claude Desktop / AI Client ↓ (MCP Protocol) MCP Server (hue-mcp) ↓ Cache Layer (hue-cache) ↓ Base SDK (hue-sdk) ↓ Hue Bridge Pro(s) ``` ## Installation ### Prerequisites - Go 1.25.6 or later - Philips Hue Bridge Pro with API access - Bridge IP address and application key ### Building ```bash cd /tmp/hue-mcp go build -o hue-mcp main.go ``` ## Configuration The server looks for configuration in `~/.config/hue-mcp/config.json` (or `$XDG_CONFIG_HOME/hue-mcp/config.json`). ### Configuration File Structure ```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" } } ``` ### Getting Your Application Key If you don't have an application key, you can generate one using the Hue SDK: ```go // TODO: Add setup wizard tool or link to hue-sdk documentation ``` ## Claude Desktop Integration Add the following to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "hue": { "command": "/tmp/hue-mcp/hue-mcp", "args": [] } } } ``` Restart Claude Desktop to load the MCP server. ## Available Tools ### Setup & Discovery - `discover_bridges` - Find Hue bridges on your network (N-UPnP via discovery.meethue.com) - `authenticate_bridge` - Authenticate with bridge (link button press required) - `add_bridge` - Add authenticated bridge to configuration - `remove_bridge` - Remove bridge from configuration - `get_config_path` - Get configuration file location ### Bridge Management - `list_bridges` - List all configured Hue bridges - `get_bridge_info` - Get detailed bridge information ### Light Control - `list_lights` - List all lights across bridges - `get_light` - Get detailed light information - `control_light` - Comprehensive single light control: - On/off, brightness (0-100%) - RGB colors via XY coordinates - Color temperature (white spectrum, 153-500 mirek) - Effects (candle, fire, prism, sparkle, opal, glisten, underwater, cosmos, sunbeam, enchant) - Timed effects (sunrise, sunset with duration) - Alert effects (breathe) - Gradient support for lightstrips - `control_lights` - Control multiple lights in one call: - Each light can have unique color, brightness, and effects - Perfect for: "set room to rainbow" or "varying shades of blue" ### Room Management - `list_rooms` - List all rooms - `get_room` - Get detailed room information ### Grouped Light Control - `list_grouped_lights` - List all grouped lights (rooms and zones) - `get_grouped_light` - Get detailed information about a grouped light - `control_room_lights` - Control all lights in a room/zone simultaneously: - Single API call controls all lights with same settings - On/off, brightness, RGB colors, color temperature, alerts - Perfect for: "turn off all bedroom lights" or "set living room to warm white" ### Scene Management - `list_scenes` - List all scenes - `get_scene` - Get detailed scene information - `activate_scene` - Activate (recall) a scene: - Optional brightness override (0-100%) - Optional transition duration (0-6000000ms) - Applies scene's lighting configuration to all lights ### Cache Management - `warm_cache` - Manually populate/refresh cache for instant access - `cache_stats` - View cache statistics (hit rate, entries, SSE sync status) ## Available Resources Resources provide read-only access to bridge data: - `bridges://status` - Status of all configured bridges - `bridges://devices` - Complete device inventory - `bridges://rooms` - All rooms across bridges - `bridges://scenes` - All scenes across bridges ## Available Prompts Prompts provide AI-assisted interactions: - `smart-lighting` - Get lighting suggestions based on activity - `create-scene` - Interactive scene creation assistant - `energy-insights` - Energy usage analysis and optimization ## Example Usage Once connected to Claude Desktop, you can interact with your lights naturally: ``` 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] ``` ## Cache Configuration The cache layer provides: - **File Backend**: Persistent cache across restarts - **Auto-Save**: Automatic cache persistence every 30 seconds - **Warm on Startup**: Pre-loads cache for instant first access - **SSE Sync**: Real-time updates from bridge via Server-Sent Events Cache files are stored in `~/.cache/hue-mcp/` by default. ## Development ### Project Structure ``` /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 ``` ### Dependencies - `github.com/mark3labs/mcp-go` - MCP SDK for Go - `github.com/rmrfslashbin/hue-sdk` - Base Hue API SDK - `github.com/rmrfslashbin/hue-cache` - Caching layer with SSE sync ## Troubleshooting ### Bridge Connection Issues 1. Verify bridge IP address is correct 2. Ensure application key is valid 3. Check network connectivity to bridge 4. Review logs in `~/.config/hue-mcp/logs/` ### Cache Issues 1. Delete cache files: `rm -rf ~/.cache/hue-mcp/` 2. Restart the MCP server 3. Verify SSE endpoint is accessible ### Claude Desktop Not Detecting Server 1. Verify server builds successfully: `go build -o hue-mcp main.go` 2. Check configuration path in `claude_desktop_config.json` 3. Restart Claude Desktop after configuration changes 4. Check Claude Desktop developer console for errors ## License [Add license information] ## Contributing [Add contribution guidelines] ## Related Projects - [hue-sdk](https://github.com/rmrfslashbin/hue-sdk) - Base Philips Hue API SDK - [hue-cache](https://github.com/rmrfslashbin/hue-cache) - Caching layer with SSE synchronization