Philips Hue MCP Server

An MCP (Model Context Protocol) server that provides tools for controlling Philips Hue smart lighting systems. This allows AI assistants like Claude to interact with your Philips Hue lights, groups, and scenes.

Features

• List and control individual lights

• Adjust brightness and color temperature

• Set colors using CIE xy color space

• Control groups/rooms of lights

• List and activate scenes

• Full async/await support for optimal performance

Prerequisites

• Python 3.10 or higher

• A Philips Hue Bridge connected to your network

• API key (username) for your Hue Bridge (see setup instructions below)

Installation

1. Clone or download this repository:

2. Create a virtual environment and install dependencies:

Option A: Using uv (Recommended - Fast)

If you have uv installed:

Option B: Using standard pip

Or install dependencies directly:

Configuration

Step 1: Find Your Hue Bridge IP Address

You can find your bridge IP address in several ways:

1. Using the Philips Hue app (Settings > Hue Bridges > i icon)

2. Using the discovery service: https://discovery.meethue.com/

3. Checking your router's DHCP client list

Step 2: Obtain an API Key

To control your Hue Bridge, you need to create an API key (called "username" in Hue terminology):

1. Press the physical button on your Hue Bridge

2. Within 30 seconds, run one of these commands:

Using curl:

Using Python:

You'll receive a response like:

Save the username value - this is your API key.

Step 3: Configure Environment Variables

Option A: Using .env file (Recommended)

1. Copy the example environment file:

2. Edit the .env file with your actual values:

The .env file is already in .gitignore so your credentials won't be committed to version control.

Option B: Manual Environment Variables

Alternatively, you can set environment variables manually:

Linux/macOS:

Windows (Command Prompt):

Windows (PowerShell):

Container Deployment (Podman/Docker)

Building the Container Image

You can run the MCP server in a container (Podman or Docker), which is useful for isolation and deployment:

Using Podman (Recommended for WSL2):

Using Docker:

Running with Compose

Podman Compose:

Docker Compose:

Using Container with Claude Desktop (Recommended)

The wrapper script run-docker-mcp.sh automatically detects Podman or Docker and allows Claude Desktop to communicate with the containerized MCP server.

Step 1: Build the container image first:

Step 2: Configure Claude Desktop

Edit your Claude Desktop config file based on your setup:

Option A: Linux (Claude Desktop on Linux)

Location: ~/.config/Claude/claude_desktop_config.json

Option B: Windows + WSL2 (MCP in WSL, Claude Desktop on Windows)

Location: %APPDATA%\Claude\claude_desktop_config.json

Full path example: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json

Alternative Windows path formats (try if the above doesn't work):

Or using the PowerShell script:

Option C: macOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Step 3: Restart Claude Desktop

The wrapper script will:

• Automatically detect whether you're using Podman or Docker

• Load environment variables from your .env file

• Run the container with --network host to access your Hue Bridge

• Handle stdio communication with Claude Desktop

• Automatically clean up the container when done

Container Networking Notes

• The container uses --network host mode to access your Hue Bridge on the local network

• This is necessary because the Hue Bridge typically doesn't have external access

• Podman on WSL2 works great with host networking

• If your container runtime doesn't support host networking, you may need to configure bridge networking differently

Usage

Running the Server Standalone

Or using the installed script:

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Or if installed globally:

Restart Claude Desktop, and you should see the Hue tools available.

Available Tools

Light Control

• list_lights - List all lights with their current state

• get_light_state - Get detailed state of a specific light

• turn_light_on - Turn a light on (optionally set brightness)

• turn_light_off - Turn a light off

• set_brightness - Set brightness level (0-254)

• set_color_temp - Set color temperature in mireds (153-500)

• set_color - Set color using CIE xy coordinates

Group Control

• list_groups - List all groups/rooms

• control_group - Control all lights in a group at once

Scene Control

• list_scenes - List all available scenes

• activate_scene - Activate a predefined scene

Example Commands

Once configured with Claude, you can use natural language:

• "Turn on the living room lights"

• "Set the bedroom light to 50% brightness"

• "Make the kitchen lights warm white"

• "Activate my reading scene"

• "Show me all available lights"

• "Turn off all lights in the office"

Development

Running Tests

Code Formatting

Troubleshooting

Connection Issues

1. Ensure your Hue Bridge is powered on and connected to your network

2. Verify the bridge IP address hasn't changed

3. Check that your API key is valid

4. Make sure you're on the same network as the Hue Bridge

API Key Issues

If your API key stops working:

1. The bridge may have been reset

2. Generate a new API key using the setup instructions

3. Update your environment variables

Light Not Responding

1. Check if the light is reachable using list_lights

2. Ensure the light is powered on (physical switch)

3. Try controlling it from the Philips Hue app first

Architecture

• server.py - Main MCP server implementation

• hue_client.py - Async wrapper around aiohue library

• tools.py - MCP tool definitions and handlers

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References

• Philips Hue API Documentation

• MCP Documentation

• aiohue Library