Metadata-Version: 2.4
Name: hue-go-mcp
Version: 0.3.1
Summary: MCP server that controls a Philips Hue light over Zigbee via zigbee2mqtt (no Hue Bridge, no Home Assistant).
License: MIT
Requires-Python: >=3.10
Requires-Dist: aiomqtt
Requires-Dist: mcp[cli]<2,>=1.27
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Description-Content-Type: text/markdown

# hue-go-mcp

An MCP server that controls a Philips **Hue** light over Zigbee via **[zigbee2mqtt](https://www.zigbee2mqtt.io/)** for setups with no Hue Bridge or Home Assistant available (such as for travel and conference scenarios). It speaks MQTT, so any MCP client can read and drive the lamp.

## Tools

| Tool | What it does |
| --- | --- |
| `set_power(on)` | Turn the lamp on/off |
| `set_brightness(level)` | Brightness, `0.0`–`1.0` |
| `set_color_rgb(r, g, b)` | Color from RGB, each `0.0`–`1.0` (zigbee2mqtt does the gamut conversion) |
| `set_color_name(name)` | Color by name: red, green, blue, yellow, cyan, magenta, orange, purple, pink, white, warm, cool |
| `set_color_temp(mired)` | White color temperature, `150` (cool) – `500` (warm) |
| `get_state()` | Read back `{power, brightness, rgb, model, color_temp_mired, available, link_quality}` |
| `pulse(count, period, min_level, max_level, color)` | Smooth "breathe" fade; restores brightness + power when done |

## How it works

```
MCP client → hue-go-mcp → MQTT broker → zigbee2mqtt → Zigbee coordinator → Hue lamp
```

## Prerequisites

1. A **Zigbee coordinator** (any zigbee2mqtt-supported USB stick) with your Hue light **paired into zigbee2mqtt**.
2. An **MQTT broker** zigbee2mqtt publishes to (e.g. [Mosquitto](https://mosquitto.org/)).
3. **Python ≥ 3.10**.

Setting up the coordinator + zigbee2mqtt + broker is standard zigbee2mqtt territory — see [zigbee2mqtt.io](https://www.zigbee2mqtt.io/guide/getting-started/). `setup-zigbee2mqtt.md` has a concrete walkthrough for a SONOFF Dongle Plus MG24 on Windows.

## Install

```bash
pip install hue-go-mcp    # from PyPI
```

Or run it without installing, straight from PyPI, with [uv](https://docs.astral.sh/uv/): `uvx hue-go-mcp`. For local development from a checkout: `pip install -e .` (or just `pip install "mcp[cli]" aiomqtt` and run `hue_go_mcp.py` directly).

## Configure

Set environment variables (only `Z2M_DEVICE` is required):

| Var | Default | Notes |
| --- | --- | --- |
| `Z2M_DEVICE` | — | The lamp's zigbee2mqtt friendly name. Find it with `python z2m_list_lights.py` |
| `MQTT_BROKER` | `localhost` | MQTT broker host |
| `MQTT_PORT` | `1883` | MQTT broker port |
| `MQTT_USERNAME` / `MQTT_PASSWORD` | — | Only if your broker requires auth |
| `Z2M_BASE_TOPIC` | `zigbee2mqtt` | zigbee2mqtt base topic |
| `HUE_MODEL` | `7602031U7` | Reported in `get_state().model` |
| `MCP_TRANSPORT` | `stdio` | `stdio` / `http` (streamable-http at `/mcp`) |

## Run

```bash
Z2M_DEVICE=hue_go python hue_go_mcp.py                    # stdio
Z2M_DEVICE=hue_go MCP_TRANSPORT=http python hue_go_mcp.py # serves /mcp
```

On Windows (PowerShell): `$env:Z2M_DEVICE="hue_go"; python hue_go_mcp.py`.

Smoke-test with the MCP Inspector: `mcp dev hue_go_mcp.py`, then call `set_power(true)`, `set_color_name("red")`, `pulse(count=2)` and watch the lamp.

## Use from an MCP client

The server talks stdio and can run anywhere that can reach the broker; the lamp only needs to be in Zigbee range of the coordinator. It only functions while your MQTT broker and zigbee2mqtt are running (see [Prerequisites](#prerequisites)) — otherwise the tools load but every call fails to reach the lamp.

### Claude Code

```bash
claude mcp add hue-go --env MQTT_BROKER=localhost --env Z2M_DEVICE=hue_go -- uvx hue-go-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "hue-go": {
      "command": "uvx",
      "args": ["hue-go-mcp"],
      "env": { "MQTT_BROKER": "localhost", "Z2M_DEVICE": "hue_go" }
    }
  }
}
```

### Any MCP client

Same shape as above: run `uvx hue-go-mcp` (or `python /absolute/path/to/hue_go_mcp.py` from a checkout) with `MQTT_BROKER` and `Z2M_DEVICE` in the environment. `uvx` requires [uv](https://docs.astral.sh/uv/); if you installed with `pip install hue-go-mcp` instead, use the `hue-go-mcp` console script it puts on your PATH as the `command`.

## Tests

```bash
pip install -e ".[test]" && pytest
```

Tests inject a fake MQTT client and assert the exact `/set` payloads and state parsing — no broker or hardware required.

## Files

- `hue_go_mcp.py` — the MCP server (FastMCP).
- `hue_mqtt.py` — zigbee2mqtt transport (`MqttLamp`) over MQTT.
- `z2m_list_lights.py` — list zigbee2mqtt devices to find `Z2M_DEVICE`.
- `setup-zigbee2mqtt.md` — coordinator + broker + pairing walkthrough (Windows / SONOFF MG24).
- `zigbee-plan.md` — design rationale.

## License

MIT
