huemcp 0.1.0

MCP server for controlling a Philips Hue bridge via the local CLIP v2 API

HueMCP

An MCP server that lets Claude (or any MCP client) discover and control a Philips Hue bridge over its local CLIP v2 HTTP API. No cloud account needed — all traffic is LAN-local to your bridge.

Tool surface

Tool	Purpose
list_lights()	Every light with on/off, brightness, colour, owner device
list_rooms()	Rooms with their grouped_light_id and member devices
list_zones()	Zones with their grouped_light_id and member lights
list_scenes(group_id=None)	Scenes, optionally filtered to one room/zone
set_light(light_id, on?, brightness?, color_temp_mirek?, color_xy?, effect?, gradient_points?, gradient_mode?, timed_effect?, timed_effect_duration_ms?, transition_ms?)	Update one light
set_group(grouped_light_id, on?, brightness?, color_temp_mirek?, color_xy?, transition_ms?)	Update all lights in a room or zone
activate_scene(scene_id, brightness?, transition_ms?, action="active")	Recall a scene
identify_light(light_id)	Briefly pulse a light to locate it
bridge_info()	Basic identity of the bridge
get_resource(rtype, rid=None)	Generic escape hatch — raw bridge payload for any resource type

brightness is a percent (0–100). color_temp_mirek is a CIE mired value (typical range 153–500 ≈ 6500K–2000K — the per-light valid range is reported by list_lights()). color_xy is [x, y] in CIE 1931 space, clamped to the light's gamut.

list_lights() also reports per-light capability: effects.available (e.g. candle, fire, prism, sparkle, opal, glisten), timed_effects.available (sunrise, sunset), and — for gradient lightstrips — a gradient block with points_capable, pixel_count, and mode_values. Pass matching values to set_light to drive them: effect="candle", gradient_points=[[x,y], ...], timed_effect="sunrise", etc.

Requirements

• Python 3.10+
• A Hue bridge reachable on your LAN
• An application key — generated by pressing the link button and POSTing to /api (see "Bridge-side setup" below)
• An MCP-capable client — these instructions assume Claude Code

Install

git clone <your-fork-url> HueMCP
cd HueMCP
python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env
# edit .env to set HUE_BRIDGE_HOST and HUE_APPLICATION_KEY

Smoke test:

.venv/bin/python scripts/smoke_test.py

Register with Claude Code (user scope, available in every project):

claude mcp add huemcp /absolute/path/to/HueMCP/.venv/bin/huemcp -s user

Bridge-side setup

1. Find your bridge's IP at https://discovery.meethue.com or in the Hue app (Settings → My Hue System).

2. Press the bridge's physical link button.

3. Within 30 seconds, request an application key:

   curl -sk -X POST https://<bridge-ip>/api \
     -H 'Content-Type: application/json' \
     -d '{"devicetype":"huemcp#'"$(hostname)"'", "generateclientkey":true}'
   

   Copy the username value from the response into HUE_APPLICATION_KEY.

TLS

The bridge presents a self-signed certificate signed by the Philips Hue root CA. By default HUE_VERIFY_TLS=0 and the client skips verification — appropriate for a LAN-local device. To verify properly, install the Hue root CA into your trust store and set HUE_VERIFY_TLS=1, or pin a CA bundle by setting HUE_VERIFY_TLS=/path/to/ca.pem.

Configuration reference

Variable	Default	Purpose
HUE_BRIDGE_HOST	(required)	Hostname or IP of the bridge
HUE_APPLICATION_KEY	(required)	Application key from the bridge
HUE_VERIFY_TLS	0	0 skip, 1 system trust, or path to CA bundle
HUE_TIMEOUT	10	Per-request timeout in seconds

License

MIT — see LICENSE.