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

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

License

MIT — see LICENSE.