Hue

You can run a local MCP server that lets AI assistants control Philips Hue lighting with natural language. This server handles discovery, scene activation, room and zone management, and intelligent responses while keeping all traffic on your local network for security and privacy.

How to use

Install and run the Hue MCP Server on a machine on your local network. Then configure your MCP client (Claude Desktop or compatible client) to connect to the server you start. Use natural language commands to control lights, create scenes, and query status. Common actions include turning on or off groups of lights, activating predefined scenes, adjusting brightness and color, and searching for lights by room or capability. The server optimizes responses, caches data to minimize bridge calls, and provides quick actions and suggestions to streamline your conversations.

How to install

Prerequisites: Node.js 18+ and Philips Hue Bridge (v2) on your local network. You also need Claude Desktop or a compatible MCP client.

Step 1 – Install dependencies and set up the project files.

git clone https://github.com/your-username/hue-mcp.git
cd hue-mcp
npm install

Step 2 – Choose a setup path. Use the web setup for a guided wizard or the CLI setup for a quick start.

Option A – Web setup (recommended): starts a setup wizard for bridge discovery, authentication, and configuration.

npm run setup:web

Option B – CLI setup: manual setup flow.

npm run setup

Step 3 – Add the MCP server to Claude Desktop. Copy the generated configuration into your Claude Desktop config file. An example layout is shown below.

{
  "mcpServers": {
    "hue_lights": {
      "command": "node",
      "args": ["/path/to/hue-mcp/dist/index.js"],
      "env": {
        "HUE_BRIDGE_IP": "192.168.1.100",
        "HUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 4 – Start using. Restart Claude Desktop, then try commands like "Turn on the living room lights" or "Activate the energize scene".

Configuration and security

Configuration is driven by environment variables, a hue-config.json file, or a .env file. The critical variables are the bridge IP and the API key. Other options control cache intervals and event updates. All communication remains local to your network and data is not sent externally.

Environment variables shown in examples include the bridge IP, API key, cache interval, and log level. The server supports fast cache-based responses with graceful fallback to live bridge data when needed.

Troubleshooting

If you encounter issues, verify the Hue bridge is powered on and on the same network. Ensure you authenticated during setup when prompted to press the bridge button. If a connection test fails, double-check the bridge IP, API key validity, and firewall settings that could block access to the bridge.

Development and testing

To run tests and lint locally, use the following commands.

# Test connection to your bridge
npm run test:connection

# Run unit tests
npm test

# Check TypeScript types
npm run typecheck

Available tools

discover_bridges

Find Hue bridges on your network and prepare for authentication.

authenticate_bridge

Authenticate with a bridge by pressing its link button and exchanging credentials.

add_bridge

Add an authenticated bridge to the server configuration.

remove_bridge

Remove a bridge from the server configuration.

get_config_path

Return the location of the server configuration file.

list_bridges

List all configured Hue bridges.

get_bridge_info

Get detailed information about a specific bridge.

list_lights

List all lights across all configured bridges.

get_light

Get detailed information about a specific light.

control_light

Control a single light with on/off, brightness, color, and effects.

control_lights

Control multiple lights in a single call with per-light settings.

list_rooms

List all rooms across all bridges.

get_room

Get detailed information about a room.

list_grouped_lights

List grouped lights such as rooms or zones.

get_grouped_light

Get details about a grouped light.

control_room_lights

Control all lights in a room/zone with a single call.

list_scenes

List all scenes across bridges.

get_scene

Get detailed information about a scene.

activate_scene

Recall a scene and optionally override brightness or transition duration.

warm_cache

Manually populate or refresh the cache for instant access.

cache_stats

View cache statistics including hit rate and entries.