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

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

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