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

• 🌐 Network-accessible by default - Control lights from any device on your network
• 💡 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
• 🏥 Health check endpoint for monitoring
• 🐳 Container-ready with Docker/Podman support

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:

cd ~/development/mcphue

2. Create a virtual environment and install dependencies:

Option A: Using uv (Recommended - Fast)

If you have uv installed:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Option B: Using standard pip

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Or install dependencies directly:

pip install mcp aiohue aiohttp pydantic python-dotenv

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:

curl -X POST http://<BRIDGE_IP>/api \
  -H "Content-Type: application/json" \
  -d '{"devicetype":"hue-mcp-server#user"}'

Using Python:

import requests
response = requests.post(
    "http://<BRIDGE_IP>/api",
    json={"devicetype": "hue-mcp-server#user"}
)
print(response.json())

You'll receive a response like:

[{"success":{"username":"1234567890abcdef1234567890abcdef"}}]

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:

cp .env.example .env

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

HUE_BRIDGE_IP=192.168.1.x
HUE_API_KEY=your-api-key-here

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:

export HUE_BRIDGE_IP="192.168.1.x"
export HUE_API_KEY="your-api-key-here"

Windows (Command Prompt):

set HUE_BRIDGE_IP=192.168.1.x
set HUE_API_KEY=your-api-key-here

Windows (PowerShell):

$env:HUE_BRIDGE_IP="192.168.1.x"
$env:HUE_API_KEY="your-api-key-here"

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

cd ~/development/mcphue

# Build the image
podman build -t hue-mcp-server:latest .

Using Docker:

cd ~/development/mcphue

# Build the image
docker build -t hue-mcp-server:latest .

Running with Compose

The default docker-compose.yml runs the server in network mode (HTTP).

Podman Compose:

# Install podman-compose if not already installed
pip install podman-compose

# Start the container in network mode (default)
podman-compose up -d

# View logs
podman-compose logs -f

# Stop the container
podman-compose down

Docker Compose:

# Start the container in network mode (default)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

Once running, the server is accessible at http://localhost:8080/mcp (or your machine's IP for remote access).

For stdio mode, use docker-compose.stdio.yml:

podman-compose -f docker-compose.stdio.yml up -d
# or
docker-compose -f docker-compose.stdio.yml up -d

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:

cd ~/development/mcphue

# Using Podman
podman build -t hue-mcp-server:latest .

# Or using Docker
docker build -t hue-mcp-server:latest .

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

{
  "mcpServers": {
    "hue": {
      "command": "/home/micro/development/mcphue/run-docker-mcp.sh"
    }
  }
}

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

{
  "mcpServers": {
    "hue": {
      "command": "\\\\wsl.localhost\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.bat"
    }
  }
}

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

{
  "mcpServers": {
    "hue": {
      "command": "\\\\wsl$\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.bat"
    }
  }
}

Or using the PowerShell script:

{
  "mcpServers": {
    "hue": {
      "command": "powershell.exe",
      "args": ["-File", "\\\\wsl.localhost\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.ps1"]
    }
  }
}

Option C: macOS

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

{
  "mcpServers": {
    "hue": {
      "command": "/path/to/mcphue/run-docker-mcp.sh"
    }
  }
}

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

Quick Start (Network Mode - Default)

The server runs in network mode by default, making it accessible from any computer on your network:

# Start the server
hue-mcp-server

# Or using Python directly
python -m hue_mcp_server.fastmcp_http_server

The server will start on http://0.0.0.0:8080 with the MCP endpoint at http://0.0.0.0:8080/mcp.

You can customize the host and port using environment variables:

MCP_HOST=0.0.0.0 MCP_PORT=8080 hue-mcp-server

Health Check:

curl http://localhost:8080/health
# {"status":"healthy","bridge_connected":true,"service":"hue-mcp-server"}

Using with Claude Desktop (Network Mode) 🌐

Network mode allows Claude Desktop to connect to the MCP server over HTTP, enabling remote access and multi-computer setups.

Step 1: Start the MCP Server

Make sure your MCP server is running in network mode:

# Start the server (runs on http://0.0.0.0:8080 by default)
hue-mcp-server

# Or start with Docker/Podman
podman-compose up -d

You should see output like:

INFO: Hue MCP HTTP Server starting on http://0.0.0.0:8080
INFO: MCP endpoint: http://0.0.0.0:8080/mcp

Step 2: Determine Your Server URL

Option A: Same Computer (Server and Claude Desktop on same machine)

• Use: http://localhost:8080/mcp

Option B: Different Computer (Server on another machine)

• Find your server's IP address:

  # On Linux/macOS
  ip addr show | grep "inet " | grep -v 127.0.0.1
  
  # On Windows (in WSL or PowerShell)
  ipconfig | findstr IPv4
  

• Use: http://YOUR_SERVER_IP:8080/mcp (e.g., http://192.168.1.50:8080/mcp)

Step 3: Verify Server is Accessible

Test the health endpoint from the computer where Claude Desktop is installed:

# Replace localhost with your server IP if on different computer
curl http://localhost:8080/health

# Expected response:
# {"status":"healthy","bridge_connected":true,"service":"hue-mcp-server"}

If you can't reach the health endpoint, check:

• Server is running (podman ps or ps aux | grep hue_mcp_server)
• Firewall allows port 8080
• Both computers are on the same network

Step 4: Configure Claude Desktop

Find your Claude Desktop config file:

Platform	Config File Location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json<br/>Full path: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Edit the config file and add the Hue MCP server configuration:

For Same Computer:

{
  "mcpServers": {
    "hue": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

For Different Computer (Remote Server):

{
  "mcpServers": {
    "hue": {
      "url": "http://192.168.1.50:8080/mcp"
    }
  }
}

Replace 192.168.1.50 with your actual server IP address

If you have other MCP servers configured, add the hue entry alongside them:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "hue": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Step 5: Restart Claude Desktop

Close Claude Desktop completely and restart it. The Hue MCP tools should now be available.

Step 6: Test the Connection

In Claude Desktop, try asking:

• "Can you list my Philips Hue lights?"
• "Turn on the living room lights"

Claude should be able to see and use the Hue MCP tools.

Troubleshooting Network Mode

Claude Desktop can't connect to MCP server:

1. Verify server is running: curl http://YOUR_SERVER:8080/health
2. Check the Claude Desktop config file has the correct URL
3. Ensure no typos in the URL (must end with /mcp)
4. Try using IP address instead of hostname

Connection works locally but not from another computer:

1. Check firewall settings on server machine
2. Verify both computers are on the same network
3. Try pinging the server: ping YOUR_SERVER_IP
4. See NETWORK_SETUP.md for detailed firewall configuration

Tools show up but don't work:

1. Check server logs: podman logs hue-mcp-server or check terminal output
2. Verify .env file has correct HUE_BRIDGE_IP and HUE_API_KEY
3. Test bridge connection: curl http://YOUR_BRIDGE_IP/api/YOUR_API_KEY/lights

Advanced Configuration:

For detailed information on network setup, firewall configuration, and multi-computer deployment, see NETWORK_SETUP.md.

Alternative: Stdio Mode (Local Only)

For local-only access via standard input/output:

# Run the stdio server
hue-mcp-stdio-server

# Or using Python directly
python -m hue_mcp_server.server

Configure Claude Desktop for stdio mode:

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

{
  "mcpServers": {
    "hue": {
      "command": "hue-mcp-stdio-server",
      "env": {
        "HUE_BRIDGE_IP": "192.168.1.x",
        "HUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or using Python directly:

{
  "mcpServers": {
    "hue": {
      "command": "python",
      "args": ["-m", "hue_mcp_server.server"],
      "env": {
        "HUE_BRIDGE_IP": "192.168.1.x",
        "HUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: Stdio mode only works when Claude Desktop is running on the same machine as the server.

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

pip install -e ".[dev]"
pytest

Code Formatting

black src/
ruff check src/

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