hue-mcp
This server lets Claude control Philips Hue lights through a local Hue Bridge via MCP, covering light state, scenes, effects, power budgets, and timers.
Inspect home: list rooms/zones, their lights' current state, scenes, and estimated watts (
get_home).Control lights: turn on/off; set brightness, relative brightness, color hex, white temperature, and fades up to 100 min (
set_lights).Set by power: light a target to an approximate total wattage (
set_power).Scenes: activate a saved scene, optionally dynamic and with transitions (
activate_scene); save the current room/zone look as a new scene (create_scene).Effects: start/stop looping effects like candle, fire, prism, sparkle, etc.; run sunrise/sunset over a duration (
set_effect).Timers: schedule bridge-run off/on/scene actions after a delay; list and cancel pending timers (
set_timer,list_timers,cancel_timer).
Allows control of Philips Hue lights through a Hue Bridge on the local network, providing tools for setting power, brightness, color, white tone, scenes, effects, and timers via the bridge's CLIP v2 and v1 schedules APIs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hue-mcp dim the living room to 30% and make it warm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hue-mcp
An MCP server that lets Claude control Philips Hue lights through a Hue Bridge on your local network. Ask in plain language: "dim the living room to 30% and make it warm", "candle effect in the bedroom", "turn everything off in 30 minutes".
It talks to the bridge directly over your LAN (no Hue cloud account involved) using the bridge's CLIP v2 API, plus the v1 schedules API for timers.
Install
Needs Python 3.12 or newer and a Hue Bridge. Tested with the square Hue Bridge (v2); the Bridge Pro speaks the same API.
git clone https://github.com/mdlopezme/hue-mcp.git && cd hue-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .On Debian/Ubuntu without the python3-venv package, create the venv with --without-pip and
bootstrap pip into it with the system pip (package python3-pip):
python3 -m pip --python .venv/bin/python install pip.
Related MCP server: Philips Hue MCP Server
Pair with the bridge
.venv/bin/hue-mcp setup # or: setup --ip 192.168.1.20Setup finds the bridge (mDNS, falling back to Signify's discovery service), asks you to press
the round link button on top of it, and saves an app key to ~/.config/hue-mcp/bridge.json,
readable only by you. Every connection verifies the bridge's certificate against Signify's root
CAs (bundled in src/hue_mcp/hue_roots.pem) and, from the first contact on, that it names the
bridge's id. (setup --ip learns that id from the bridge itself, over a connection whose
certificate must still chain to Signify's roots.)
Use it from Claude Code
claude mcp add --scope user hue -- /absolute/path/to/hue-mcp/.venv/bin/hue-mcpTool | Does |
| Rooms and zones, their lights' state, their scenes, and estimated watts |
| On/off, brightness (absolute or relative), color, white tone, fades of up to 100 min |
| "Use 20 watts": one brightness for every light in the target, to fit the budget |
| Recall a scene, or save a room's current look as a new one |
| candle, fire, prism and other looping effects; sunrise/sunset over up to 6 h; |
| "Turn the bedroom off in 30 minutes", run by the bridge |
| Adaptive focus rounds whose looks follow the sun; see Pomodoro |
Good to know:
Fades and timers run on the bridge, so they finish even after the Claude session ends.
Timers use the bridge's v1 schedules (API v2 has none), so the Hue app doesn't show them. At most 10 can be pending at once; the bridge's schedule slots are shared with other apps.
list_timerscounts down with this computer's clock; the bridge fires them by its own.Scenes made with
create_scenestay on the bridge; delete them in the Hue app.Names match exactly or by a unique part ("living" finds "Living room"). Misspellings are only suggested, never acted on, and
allmust be spelled out.Partial success: when a light in a group doesn't respond, the command still reaches the others and Claude is told which part may not have taken effect.
Hue bulbs sometimes switch themselves back on right after being turned off, mostly after a fade or a room-wide off. It's a known quirk of the bulbs, not of this server (see zigbee2mqtt #20336); asking again turns them off.
Watts are estimates. Hue bulbs don't report their draw, so
get_homeandset_powermodel it: about 0.5 W standby while off, rising linearly with brightness to the bulb's rating. Ratings for known models are insrc/hue_mcp/power.py; other bulbs are assumed to be 9 W.
Pomodoro
start_pomodoro runs focus rounds (25 minutes by default) with breaks between them, told apart by
the room's lights:
Focus looks follow the part of the day at your location: fresh blues in the morning, sunny yellows at midday, golden oranges in the afternoon, sunset rose in the evening, and a dim, blue-free red at night. A task light, such as a desk lamp, stays a white to read by, warming as the day goes.
Short breaks are greens (5 minutes), and the long break after the last round is violet (30 minutes). At night both turn dimmer and warmer.
When a break ends and you're away from the computer, the room keeps the break look and pulses red every 30 seconds. The next round starts when you're back: a mouse move or a key press. If you keep working through a break, the lights breathe brighter to send you off, and a minute before a break ends they dip as a heads-up (breaks of two minutes or less skip both).
A session ends when you ask Claude to stop it; when someone changes the room's lights at the switch or in the Hue app while it waits for you (the lights stay as they set them); or after two hours away (the room fades off).
get_pomodorotells the current phase and counts the rounds completed each day. Desktop notifications mark each switch.
A background service, the watcher, runs the sessions: it notices when you're at the computer and
switches the lights. It needs a Wayland compositor that offers the input idle notifications of
ext-idle-notify-v1 version 2 (tested on KDE Plasma 6), and it only ever learns whether you're
using the computer, never what you type. Set it up once:
.venv/bin/hue-mcp set-location "Lisbon" # where the lights are, for the sun times
.venv/bin/hue-mcp install-watcher # a systemd user service, started at every login;
# run it again after an update to restart it
.venv/bin/hue-mcp watch --print-activity # optional: check it sees you go idle and come backset-location looks the city up once with Open-Meteo's free place
search and saves its coordinates to ~/.config/hue-mcp/location.json; the sun times are then
computed locally. The first session in a room creates nine scenes there ("Pomodoro morning",
"Pomodoro short break", ...). Change one in the Hue app, or ask Claude to tweak the lights
mid-session: the change lasts until the next switch or nudge, unless save_pomodoro_look keeps
it in the look showing. Naming a task light later gives it its white in the existing looks, and
a light added to the room joins them. The watcher keeps its state and the
rounds log in ~/.local/state/hue-mcp/; its log is journalctl --user -u hue-mcp-watch.
Permissions
Claude Code asks before each tool call. You can allow mcp__hue in /permissions to skip the
prompts, but note that light, room and scene names come from the bridge and are shown to Claude
as-is: anyone who can rename your lights can put text in front of Claude.
Development
.venv/bin/python -m pip install -e '.[dev]'
make check # ruff (lint + format), mypy --strict, pytest with branch coverage
make format # apply ruff's fixes and formattingCI runs make check on Python 3.12, 3.13 and 3.14 for pushes to main and for every pull
request, and weekly to catch breaking upstream releases. Dependabot proposes dependency and
action updates.
The tests use a fake bridge, so they can't prove the real bridge agrees. Before releasing a change to what is sent to the bridge, run the hardware check. It drives every tool through the installed server against the lights you pick, checks what each light actually does, and puts them back afterwards (about eight minutes; the lights change, flicker and switch on and off). Its pomodoro step runs the watcher's logic with second-long phases, so it needs a location set:
.venv/bin/python scripts/live_check.py --light "Desk" # or --all, or --light repeatedA fade or timer failure that doesn't reproduce is most likely a bulb, not the code: bulbs with a weak Zigbee link drop the odd command, and Hue bulbs sometimes switch back on after an off.
License
MIT; see LICENSE.
Available Tools
9 toolsactivate_sceneC
Activate a saved scene.
Inputs: scene (required), room, dynamic, transition_seconds. Returns: object
cancel_timerB
Cancel a timer from list_timers.
Inputs: timer_id (required). Returns: object
create_sceneB
Save the current look of a room or zone's lights as a new scene.
Inputs: name (required), room (required). Returns: object
get_homeBRead-only
Rooms and zones, with their lights' current state and their scenes.
Inputs: room. Returns: object
list_timersBRead-only
Timers set with set_timer that haven't fired yet.
Inputs: no named parameters. Returns: object
set_effectA
Start a light effect, or stop effects with "none".
candle, fire, prism, sparkle, opal, glisten, underwater, cosmos, sunbeam and enchant loop until stopped. sunrise and sunset brighten or dim gradually over duration_minutes (wake-up light, falling asleep). Lights that don't support the effect are skipped.
Inputs: effect (required), target (required), speed, target_type, +1 more. Returns: object
set_lightsB
Turn lights on or off, or change their brightness, color or white tone.
Setting brightness, a color or a white tone also turns the lights on.
Inputs: target (required), on, color_hex, brightness, +4 more. Returns: object
set_powerA
Light the target with about this many watts in total, e.g. "use 20 watts".
Every light in the target is turned on at the same brightness; colors and white tones stay as they are.
Inputs: watts (required), target, target_type, transition_seconds. Returns: object
set_timerA
Do something after a delay, e.g. turn the bedroom off in 30 minutes.
The timer runs on the bridge, so it fires even after this conversation ends.
Inputs: target (required), minutes (required), action, target_type. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target distinct actions or resources: get_home is read-only, scene tools, timer tools, and set_effect are clearly separate. The main overlap is set_lights vs set_power, since both affect brightness, but set_power uses total wattage and preserves color, making misselection unlikely though possible.
All nine tools use a consistent snake_case verb_noun pattern (get_home, set_lights, activate_scene, list_timers, etc.). The convention is predictable and easy to follow.
Nine tools is well within the ideal 3-15 range for a smart-lighting controller. Each tool earns its place by covering state read, light control, power, scenes, effects, and timers.
Core Hue workflows are covered: state inspection, on/off, brightness/color/white tone, wattage, scenes, effects, and timers. Minor gaps include no delete/update for scenes and no update for timers, though agents can work around by cancelling and recreating.
Maintenance
Related MCP Connectors
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Manage your IoT device fleet directly from Claude. Create device templates with datastreams and events, provision new devices, read live sensor data, and control outputs. The Blynk connector integrates with the Blynk IoT platform, enabling direct configuration and monitoring of connected devices and infrastructure.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables control of Philips Hue lights through VS Code Copilot or Claude Desktop using natural language commands. Supports turning lights on/off, adjusting brightness, changing colors, and listing available lights on your Hue Bridge.2-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Philips Hue smart lighting systems, including individual lights, groups, scenes, brightness, and color adjustments through natural language commands.-
- AlicenseAqualityDmaintenanceEnables control of Philips Hue lights via Bluetooth LE directly from Claude, without requiring a Hue Bridge or internet connection.81MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to control Philips Hue smart lighting systems using natural language, supporting light control, group management, scenes, and presets.MIT