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 - 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: ```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 **Podman Compose:** ```bash # Install podman-compose if not already installed pip install podman-compose # Start the container (reads .env file automatically) podman-compose up -d # View logs podman-compose logs -f # Stop the container podman-compose down ``` **Docker Compose:** ```bash # Start the container (reads .env file automatically) docker-compose up -d # View logs docker-compose logs -f # Stop the container docker-compose down ``` ### 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 ### Running the Server Standalone ```bash python -m hue_mcp_server.server ``` Or using the installed script: ```bash hue-mcp-server ``` ### 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` ```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" } } } } ``` Or if installed globally: ```json { "mcpServers": { "hue": { "command": "hue-mcp-server", "env": { "HUE_BRIDGE_IP": "192.168.1.x", "HUE_API_KEY": "your-api-key-here" } } } } ``` 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)