hue-go-mcp 0.3.1

MCP server that controls a Philips Hue light over Zigbee via zigbee2mqtt (no Hue Bridge, no Home Assistant).

hue-go-mcp

An MCP server that controls a Philips Hue light over Zigbee via zigbee2mqtt 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).
3. Python ≥ 3.10.

Setting up the coordinator + zigbee2mqtt + broker is standard zigbee2mqtt territory — see zigbee2mqtt.io. setup-zigbee2mqtt.md has a concrete walkthrough for a SONOFF Dongle Plus MG24 on Windows.

Install

pip install hue-go-mcp    # from PyPI

Or run it without installing, straight from PyPI, with 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

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) — otherwise the tools load but every call fails to reach the lamp.

Claude Code

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):

{
  "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; 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

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