Philips Hue MCP Server (Enterprise)

A production-ready MCP (Model Context Protocol) server that provides HTTP-based tools for controlling Philips Hue smart lighting systems. Designed for local network deployment in containerized environments like Kubernetes.

Features

• 🔐 HTTPS with self-signed certificates - Secure TLS via nginx-local ingress for local network deployment
• 💡 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 Kubernetes probes
• 🔒 Transport security with allowed hosts/origins configuration
• 🐳 Production-ready Kubernetes manifests with nginx-local ingress
• 🚀 ArgoCD GitOps deployment ready

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

The server runs in HTTP mode by default, accessible on your local 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.

Environment Variables:

# Required
export HUE_BRIDGE_IP="10.1.1.207"
export HUE_API_KEY="your-api-key-here"

# Optional (defaults shown)
export MCP_HOST="0.0.0.0"
export MCP_PORT="8080"

# Optional: Transport security for local network
export MCP_ALLOWED_HOSTS="mcphue.local.shadyknollcave.io,mcphue.local.shadyknollcave.io:*"
export MCP_ALLOWED_ORIGINS="https://mcphue.local.shadyknollcave.io"

Health Check:

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

Kubernetes Deployment (Production)

This server includes production-ready Kubernetes manifests:

# Apply base manifests (default namespace: mcp)
kubectl apply -k k8s/overlays/production

# Check pod status
kubectl get pods -n mcp

# View logs
kubectl logs -n mcp -l app=mcphue

# Check health endpoint
kubectl port-forward -n mcp svc/mcphue 8080:8080
curl http://localhost:8080/health

Manifest Structure:

• k8s/base/ - Base deployment, service, namespace
• k8s/overlays/production/ - Production configuration with:
  • Resource limits and requests
  • Replicas configuration
  • Transport security settings
  • nginx-local ingress for HTTPS with self-signed certificates
  • SealedSecrets for secure credentials

The deployment includes:

• Liveness/Readiness probes - /health endpoint monitoring
• Resource limits - CPU: 1, Memory: 1Gi (requests: 200m CPU, 256Mi memory)
• Horizontal Pod Autoscaler ready (replica patches included)
• TLS termination via nginx-local ingress with self-signed certificates
• HTTPS endpoints for secure MCP communication

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 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.

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

HTTP-Based Enterprise Design:

• fastmcp_http_server.py - FastMCP HTTP server with Streamable HTTP transport
  • Runs as long-running uvicorn service
  • Exposes /health endpoint for Kubernetes probes
  • Exposes /mcp endpoint for MCP protocol communication
  • Implements transport security (allowed hosts/origins)
• hue_client.py - Async wrapper around aiohue library (Hue API v2)
• validation.py - Input validation for all tool parameters
• Container runs HTTP mode by default for production deployment

Transport Security: The HTTP server supports security restrictions for production use:

• MCP_ALLOWED_HOSTS - Whitelist allowed hostnames
• MCP_ALLOWED_ORIGINS - Whitelist CORS origins
• DNS rebinding protection enabled by default

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

CI/CD Test Tue Jan 20 19:20:25 EST 2026