# 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

```bash
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:

```bash
.venv/bin/python scripts/smoke_test.py
```

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

```bash
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:

   ```bash
   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`.