What You Can Do

Once connected, your AI assistant gets full control over your Philips Hue lighting system through natural language.

Control Lights: Turn lights on/off, set brightness, change colors, and adjust color temperature.
Manage Rooms & Zones: Control entire rooms or zones at once. List all rooms and their current states.
Activate Scenes: Browse and activate saved scenes including both built-in and custom scenes.
Create Animated Scenes: Build keyframe-based animated scenes with per-light tracks and easing options.
Play Animations: Start, stop, and manage animated scene playback in any room or zone.
Bridge Status: View connected Hue bridges, their status, and the lights available on each.

Prerequisites

1Hue Companion installed on your Windows PC
2MCP server enabled in Hue Companion settings (Settings → MCP Server → toggle on)
3A supported AI client: Claude Desktop, Claude Code, or VS Code with Copilot

Setup Instructions

Open the Claude Desktop config file. You can find it at:

%APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it.

Add the following to the config file. If the file already has content, merge the mcpServers entry into the existing object.

{
  "mcpServers": {
    "hue-companion": {
      "command": "C:\\Program Files\\HueCompanion\\HueCompanion.Mcp.exe",
      "args": ["--stdio"]
    }
  }
}

Restart Claude Desktop for the changes to take effect.

The path above is a placeholder. Your actual install path may differ. For the correct path, use the copy button in Hue Companion's Settings → MCP Server section, which auto-detects it.

Easier way: copy from the app

Hue Companion's Settings page has copy buttons that generate the config with the correct executable path for your system. Go to Settings → MCP Server and use the copy button for your AI client.

Example Prompts

Once connected, try asking your AI assistant things like:

“Turn off all the lights in the bedroom”

“Set the living room to a warm sunset mood”

“Create an animated scene that slowly cycles through ocean colors”

“What lights are currently on?”

“Set the office to 50% brightness with a cool white tone”

“Play the 'Chill Evening' scene in the lounge”

Troubleshooting

“Server not found” or connection error

Verify the executable path in your config file is correct. Open Hue Companion and go to Settings → MCP Server to copy the config with the auto-detected path. For VS Code, make sure Hue Companion is running.

Lights not responding

Check that your Hue Bridge is connected in Hue Companion. The MCP server uses the same bridge connections as the app. Go to Settings → Hue Bridge to verify your bridge is connected.

MCP server not starting

Make sure the MCP server toggle is enabled in Hue Companion's settings. The server starts automatically when the app launches (if enabled). Try toggling it off and on again.

Changes to config not taking effect

Claude Desktop and Claude Code require a restart after editing their config files. VS Code requires a window reload (Ctrl+Shift+P → “Reload Window”).