Philips Hue MCP Service

A FastMCP service that provides tools and resources for controlling Philips Hue lights through the Model Context Protocol.

Installation

1. Install dependencies:

pip install fastmcp qhue requests

Or install from the project directory:

pip install -e .

Setup

1. Find your Hue Bridge IP

• Open the Philips Hue app on your phone
• Go to Settings > My Hue System > [Your Bridge Name]
• Note the IP address

2. Create a Username/API Key

You need to create a username (API key) for your bridge:

1. Press the physical button on your Hue bridge
2. Within 30 seconds, run this Python script:

import requests
import json

bridge_ip = "192.168.1.123"  # Replace with your bridge IP
response = requests.post(f"http://{bridge_ip}/api", 
                        json={"devicetype": "hue_mcp_service#user"})
print(json.dumps(response.json(), indent=2))

1. Save the returned username/API key

Usage

Running the Service

python hue_mcp_service.py

Available Tools

• connect_to_bridge(bridge_ip, username) - Connect to your Hue bridge
• turn_light_on(light_id) - Turn on a specific light
• turn_light_off(light_id) - Turn off a specific light
• set_light_brightness(light_id, brightness) - Set brightness (0-254)
• set_light_color(light_id, hue, saturation) - Set color using hue/saturation values
• set_light_xy_color(light_id, x, y) - Set color using CIE xy coordinates

Available Resources

• lights - Get information about all lights
• light/{light_id} - Get detailed information about a specific light
• bridge-status - Get current bridge connection status

Example Usage

First, connect to your bridge:

connect_to_bridge("192.168.1.123", "your-username-here")

Then control your lights:

# Turn on light 1
turn_light_on("1")

# Set brightness to 50%
set_light_brightness("1", 127)

# Set to red color
set_light_color("1", 0, 254)

Color Values

Hue and Saturation

• Hue: 0-65535 (color wheel position)
  • 0: Red
  • 10922: Yellow
  • 21845: Green
  • 32768: Cyan
  • 43690: Blue
  • 54613: Magenta
• Saturation: 0-254 (color intensity, 0=white, 254=full color)

CIE xy Coordinates

• x, y: 0.0-1.0 (precise color specification in CIE color space)
• Common colors:
  • Red: (0.675, 0.322)
  • Green: (0.4091, 0.518)
  • Blue: (0.167, 0.04)
  • White: (0.3127, 0.329)

Requirements

• Python 3.8+
• FastMCP 2.0+
• qhue 2.0+
• requests 2.25+