Philips Hue MCP Server

# Windows + WSL2 Setup Guide This guide is for users running: - **Claude Desktop** on Windows - **MCP Server (Podman container)** in WSL2 ## Quick Setup ### 1. Verify Your Setup In WSL2, verify everything is working: ```bash cd ~/development/mcphue # Check that Podman image is built podman images | grep hue-mcp-server # Test the connection source .venv/bin/activate python test_connection.py ``` ### 2. Locate Claude Desktop Config on Windows Open File Explorer and navigate to: ``` %APPDATA%\Claude ``` Or the full path: ``` C:\Users\<YourUsername>\AppData\Roaming\Claude ``` You need to edit: `claude_desktop_config.json` ### 3. Add MCP Server Configuration Open `claude_desktop_config.json` in Notepad or your preferred editor. Add this configuration (choose ONE option): **Option 1: Using .bat file (Recommended)** ```json { "mcpServers": { "hue": { "command": "\\\\wsl.localhost\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.bat" } } } ``` **Option 2: Using .ps1 file (Alternative)** ```json { "mcpServers": { "hue": { "command": "powershell.exe", "args": ["-File", "\\\\wsl.localhost\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.ps1"] } } } ``` **Option 3: Older Windows versions (if wsl.localhost doesn't work)** ```json { "mcpServers": { "hue": { "command": "\\\\wsl$\\Ubuntu\\home\\micro\\development\\mcphue\\run-mcp-windows.bat" } } } ``` ### 4. Test WSL Path Access from Windows Before restarting Claude, verify Windows can access the WSL path: 1. Open Command Prompt (cmd.exe) on Windows 2. Run: ```cmd dir \\wsl.localhost\Ubuntu\home\micro\development\mcphue ``` You should see the project files listed. ### 5. Restart Claude Desktop 1. Completely quit Claude Desktop (right-click system tray icon → Quit) 2. Wait 5 seconds 3. Restart Claude Desktop ### 6. Verify MCP Server is Connected In Claude Desktop: 1. Look for the MCP server indicator (usually in the UI) 2. Try a command: "List all my Hue lights" 3. Claude should be able to see and control your lights! ## Troubleshooting ### Issue: "Command not found" or path not accessible **Solution 1:** Use direct wsl.exe call Create a new file `C:\Users\<YourUsername>\run-hue-mcp.bat`: ```batch @echo off wsl.exe -d Ubuntu bash -c "cd /home/micro/development/mcphue && ./run-docker-mcp.sh" ``` Then in `claude_desktop_config.json`: ```json { "mcpServers": { "hue": { "command": "C:\\Users\\<YourUsername>\\run-hue-mcp.bat" } } } ``` **Solution 2:** Check WSL distribution name ```cmd wsl -l -v ``` If your distribution isn't called "Ubuntu", update the scripts: - Edit `run-mcp-windows.bat` - Edit `run-mcp-windows.ps1` - Replace "Ubuntu" with your actual distribution name ### Issue: Container not starting 1. In WSL2, test manually: ```bash cd ~/development/mcphue ./run-docker-mcp.sh ``` 2. Check Podman is running: ```bash podman ps podman images | grep hue-mcp-server ``` 3. Rebuild if needed: ```bash podman build -t hue-mcp-server:latest . ``` ### Issue: Claude Desktop not seeing the MCP server 1. Check Claude Desktop logs (if available) 2. Verify the config file has valid JSON (use a JSON validator) 3. Make sure you completely restarted Claude Desktop 4. Check Windows Firewall isn't blocking WSL communication ### Issue: Permission denied In WSL2: ```bash chmod +x ~/development/mcphue/run-docker-mcp.sh chmod +x ~/development/mcphue/run-mcp-windows.bat chmod +x ~/development/mcphue/run-mcp-windows.ps1 ``` ## How It Works ``` ┌─────────────────────────────────────────────────────┐ │ Windows Environment │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Claude Desktop (Windows) │ │ │ │ │ │ │ │ Reads: %APPDATA%\Claude\ │ │ │ │ claude_desktop_config.json │ │ │ └──────────────┬───────────────────────────────┘ │ │ │ │ │ │ stdio │ │ │ │ │ ┌──────────────▼───────────────────────────────┐ │ │ │ run-mcp-windows.bat │ │ │ │ Calls: wsl.exe -d Ubuntu bash ... │ │ │ └──────────────┬───────────────────────────────┘ │ └─────────────────┼───────────────────────────────────┘ │ ┌─────────────────▼───────────────────────────────────┐ │ WSL2 Ubuntu Environment │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ run-docker-mcp.sh │ │ │ │ - Loads .env │ │ │ │ - Detects podman/docker │ │ │ └──────────────┬───────────────────────────────┘ │ │ │ │ │ ┌──────────────▼───────────────────────────────┐ │ │ │ Podman Container │ │ │ │ - hue-mcp-server:latest │ │ │ │ - Connects to Hue Bridge (192.168.1.112) │ │ │ │ - Exposes MCP tools │ │ │ └──────────────┬───────────────────────────────┘ │ └─────────────────┼───────────────────────────────────┘ │ │ HTTP/HTTPS │ ┌─────────────▼───────────────┐ │ Philips Hue Bridge │ │ 192.168.1.112 │ │ - 24 lights │ │ - 15 rooms │ └─────────────────────────────┘ ``` ## Testing the Full Stack ### Test 1: WSL → Podman → Hue Bridge ```bash # In WSL2 cd ~/development/mcphue ./run-docker-mcp.sh # Should start server and connect to bridge # Press Ctrl+C to stop ``` ### Test 2: Windows → WSL ```cmd REM In Windows Command Prompt \\wsl.localhost\Ubuntu\home\micro\development\mcphue\run-mcp-windows.bat REM Should start server REM Press Ctrl+C to stop ``` ### Test 3: Claude Desktop → Full Stack 1. Configure Claude Desktop with the JSON config 2. Restart Claude Desktop 3. Type: "List my Hue lights" 4. Should show all 24 lights! ## Additional Notes - The container uses `--network host` mode to access your local Hue Bridge - WSL2 and Windows share the same network interface by default - Your credentials in `.env` are never exposed to Windows - Each time Claude calls the MCP server, a fresh container starts - The `--rm` flag ensures containers are cleaned up automatically - Podman is daemonless, so no background service is needed ## Support If you encounter issues: 1. Check all paths are correct 2. Verify WSL2 is running: `wsl --status` 3. Test each component separately (see Testing section) 4. Check Windows Event Viewer for errors 5. Review Claude Desktop logs if available