Philips Hue MCP Server

# Network Access Setup This guide explains how to make the Hue MCP server accessible from other computers on your network. ## Overview The MCP server can run in two modes: 1. **Stdio Mode** (default): Local-only access via standard input/output 2. **HTTP Mode**: Network-accessible via Streamable HTTP transport (modern MCP protocol) ## HTTP Mode Setup The HTTP server uses **FastMCP** with Streamable HTTP transport - the modern, recommended protocol for network-accessible MCP servers. ### 1. Install Dependencies ```bash # Install with HTTP server dependencies (includes FastMCP) pip install -e . # Or install specific packages pip install mcp starlette uvicorn ``` ### 2. Configure Environment Add these to your `.env` file: ```bash # Required HUE_BRIDGE_IP=192.168.1.112 HUE_API_KEY=your-api-key-here # Optional - HTTP server settings MCP_HOST=0.0.0.0 # Listen on all network interfaces MCP_PORT=8080 # Port for the HTTP server ``` ### 3. Start the HTTP Server ```bash # Using the installed script hue-mcp-http-server # Or directly python -m hue_mcp_server.http_server ``` You should see output like: ``` INFO:__main__:Configuration loaded: Bridge IP = 192.168.1.112, Host = 0.0.0.0, Port = 8080 INFO:__main__:Hue MCP HTTP Server starting on http://0.0.0.0:8080 INFO:__main__:SSE endpoint: http://0.0.0.0:8080/sse INFO:__main__:Other computers can connect to: http://<this-machine-ip>:8080/sse INFO:uvicorn:Started server process INFO:uvicorn:Waiting for application startup. INFO:__main__:Starting Hue MCP HTTP Server... INFO:uvicorn:Application startup complete. INFO:uvicorn:Uvicorn running on http://0.0.0.0:8080 ``` ### 4. Find Your Server's IP Address On the machine running the server: ```bash # Linux/macOS hostname -I | awk '{print $1}' # Or ip addr show | grep "inet " | grep -v 127.0.0.1 # Windows ipconfig | findstr IPv4 ``` Example output: `192.168.1.50` ### 5. Connect from Other Computers From another computer on the same network, you can now connect to: ``` http://192.168.1.50:8080/mcp ``` ### 6. Health Check Endpoint The HTTP server includes a health check endpoint for monitoring and load balancers: ```bash # Check server health curl http://192.168.1.50:8080/health # Healthy response (200 OK): { "status": "healthy", "bridge_connected": true, "service": "hue-mcp-server" } # Unhealthy response (503 Service Unavailable): { "status": "unhealthy", "bridge_connected": false, "service": "hue-mcp-server", "error": "Hue Bridge not connected" } ``` This endpoint is useful for: - Container orchestration health checks (Docker/Podman/Kubernetes) - Load balancer health monitoring - Automated monitoring systems - Verifying the server is running and connected to the Hue Bridge ## Using with Claude Desktop (Network Mode) ### On the Server Machine 1. Start the HTTP server: ```bash hue-mcp-http-server ``` ### On Client Machines Edit Claude Desktop config to use the HTTP endpoint: **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": { "url": "http://192.168.1.50:8080/mcp" } } } ``` Replace `192.168.1.50` with your server's actual IP address. ## Container Deployment (Network Access) ### Using Podman/Docker Compose Create a new `docker-compose.http.yml`: ```yaml version: '3.8' services: hue-mcp-http-server: build: . image: hue-mcp-server:latest container_name: hue-mcp-http-server network_mode: host env_file: - .env restart: unless-stopped command: ["python", "-m", "hue_mcp_server.http_server"] ``` Run it: ```bash # Build the image podman build -t hue-mcp-server:latest . # Start the HTTP server podman-compose -f docker-compose.http.yml up -d # View logs podman logs -f hue-mcp-http-server ``` Or run directly: ```bash podman run -d \ --name hue-mcp-http-server \ --network host \ --env-file .env \ hue-mcp-server:latest \ python -m hue_mcp_server.http_server ``` ## Firewall Configuration ### Linux (ufw) ```bash sudo ufw allow 8080/tcp sudo ufw reload ``` ### Linux (firewalld) ```bash sudo firewall-cmd --permanent --add-port=8080/tcp sudo firewall-cmd --reload ``` ### Windows Firewall ```powershell New-NetFirewallRule -DisplayName "Hue MCP Server" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow ``` ### macOS ```bash # macOS firewall typically allows outbound by default # If you have a firewall enabled, add an exception for port 8080 ``` ## Security Considerations ⚠️ **Important Security Notes:** 1. **No Authentication**: The HTTP server does not include authentication. Anyone on your network can control your lights. 2. **Local Network Only**: Only run this on a trusted local network (home WiFi). Do NOT expose it to the internet. 3. **Firewall**: Consider restricting access to specific IP addresses if your firewall supports it. 4. **HTTPS**: For production use, consider adding HTTPS with a reverse proxy (nginx, Caddy, Traefik). ### Adding Basic Authentication (Optional) For added security, you can put the HTTP server behind a reverse proxy with authentication. Example with Caddy: ```caddyfile hue.local:8080 { basicauth { alice $2a$14$... # Use caddy hash-password to generate } reverse_proxy localhost:8080 } ``` ## Testing Network Access From another computer: ```bash # Test health check endpoint (simplest test) curl http://192.168.1.50:8080/health # Expected response (indicates server is healthy): # {"status":"healthy","bridge_connected":true,"service":"hue-mcp-server"} # Test if the MCP endpoint is reachable (should return an error about missing Accept header) curl http://192.168.1.50:8080/mcp # Expected response (indicates server is running): # {"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Not Acceptable: Client must accept text/event-stream"}} ``` ## Troubleshooting ### Server Not Accessible 1. Check the server is running: ```bash netstat -tuln | grep 8080 # Or ss -tuln | grep 8080 ``` 2. Verify firewall allows port 8080 3. Ensure both machines are on the same network 4. Try connecting from the server itself: ```bash curl http://localhost:8080/sse ``` ### Connection Refused - Verify `MCP_HOST=0.0.0.0` in your `.env` file - Check that no other service is using port 8080 - Try a different port (update `MCP_PORT`) ### Hue Bridge Not Reachable If the server is in a container and can't reach the Hue Bridge: - Ensure `--network host` is used - Verify the bridge IP is correct - Check that the container host can ping the bridge ## Performance Notes - **Latency**: Network mode adds ~10-50ms latency vs stdio mode - **Concurrent Clients**: The HTTP server can handle multiple Claude Desktop instances simultaneously - **Resource Usage**: Minimal overhead - mainly network I/O ## Alternative: SSH Tunneling If you only need access from one remote machine, SSH tunneling is simpler and more secure: ```bash # On the remote machine, create an SSH tunnel ssh -L 8080:localhost:8080 user@server-machine # Then configure Claude Desktop to use localhost:8080 ``` This way, the MCP server only needs to listen on localhost, and SSH provides encryption and authentication.