Philips Hue MCP Server

# 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: ```bash cd ~/development/mcphue ``` 2. Create a virtual environment and install dependencies: **Option A: Using uv (Recommended - Fast)** If you have [uv](https://github.com/astral-sh/uv) installed: ```bash uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e . ``` **Option B: Using standard pip** ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e . ``` Or install dependencies directly: ```bash 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: ```bash curl -X POST http://<BRIDGE_IP>/api \ -H "Content-Type: application/json" \ -d '{"devicetype":"hue-mcp-server#user"}' ``` Using Python: ```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: ```json [{"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: ```bash cp .env.example .env ``` 2. Edit the `.env` file with your actual values: ```bash 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:** ```bash export HUE_BRIDGE_IP="192.168.1.x" export HUE_API_KEY="your-api-key-here" ``` **Windows (Command Prompt):** ```cmd set HUE_BRIDGE_IP=192.168.1.x set HUE_API_KEY=your-api-key-here ``` **Windows (PowerShell):** ```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):** ```bash cd ~/development/mcphue # Build the image podman build -t hue-mcp-server:latest . ``` **Using Docker:** ```bash 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:** ```bash # 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:** ```bash # 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`: ```bash 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: ```bash 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` ```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` ```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): ```json { "mcpServers": { "hue": { "command": "\\\\wsl$\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.bat" } } } ``` Or using the PowerShell script: ```json { "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` ```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: ```bash # 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: ```bash MCP_HOST=0.0.0.0 MCP_PORT=8080 hue-mcp-server ``` **Health Check:** ```bash 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: ```bash # 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: ```bash # 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: ```bash # 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:** ```json { "mcpServers": { "hue": { "url": "http://localhost:8080/mcp" } } } ``` **For Different Computer (Remote Server):** ```json { "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: ```json { "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](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](NETWORK_SETUP.md). ### Alternative: Stdio Mode (Local Only) For local-only access via standard input/output: ```bash # 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` ```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: ```json { "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 ```bash pip install -e ".[dev]" pytest ``` ### Code Formatting ```bash 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](https://developers.meethue.com/) - [MCP Documentation](https://modelcontextprotocol.io/) - [aiohue Library](https://github.com/home-assistant-libs/aiohue)