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

Related MCP server: Hass-MCP

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

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

{
  "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:

// 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):

{
  "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 - Base Philips Hue API SDK

• hue-cache - Caching layer with SSE synchronization