io.github.jonnyblankinship/hue-ble-mcp
Allows controlling Philips Hue lights via Bluetooth LE, providing tools to turn on/off, set brightness, color temperature, RGB color, and apply scenes.
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., "@io.github.jonnyblankinship/hue-ble-mcp Turn on the reading light and set it to warm white"
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-ble-mcp
An MCP server that lets Claude control Philips Hue lights via Bluetooth LE — no Hue Bridge or internet connection required.
Just ask Claude things like:
"Turn off the light"
"Set the light to a warm reading mode"
"Make it a deep blue"
"Dim it to 20%"
Tools
Tool | Description |
| Discover nearby Hue BLE lights and get their addresses |
| Turn a light on |
| Turn a light off |
| Set brightness 1–100% |
| Set white color temperature (2000K warm → 6500K cool) |
| Set RGB color |
| Read current power, brightness, and color mode |
| Apply a preset: |
Related MCP server: Philips Hue MCP Server
Requirements
macOS (uses CoreBluetooth via bleak)
Python 3.10+
A Philips Hue light with Bluetooth support (most lights made after 2019)
Claude Desktop
Installation
Option 1: pip (recommended)
pip install hue-ble-mcpThen add to your ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"hue-ble": {
"command": "hue-ble-mcp",
"env": {
"HUE_LIGHT_ADDRESS": ""
}
}
}
}Option 2: Clone and run
git clone https://github.com/jonnyblankinship/hue-ble-mcp.git
cd hue-ble-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txtThen add to your claude_desktop_config.json:
{
"mcpServers": {
"hue-ble": {
"command": "/absolute/path/to/hue-ble-mcp/venv/bin/python",
"args": ["/absolute/path/to/hue-ble-mcp/server.py"],
"env": {
"HUE_LIGHT_ADDRESS": ""
}
}
}
}First-time setup
1. Pair your light
Hue BLE lights need to be in pairing mode the first time you connect. The easiest way is to reset the light via the Hue app (Settings → Light setup → select light → Delete), which puts it back into factory pairing mode.
After the first successful connection, macOS remembers the bond and you won't need to do this again.
2. Find your light's address
Restart Claude Desktop, then ask:
"Scan for my Hue lights"
Claude will return something like:
[
{
"name": "Signe gradient floor",
"address": "77577FFA-2F08-CAFD-5F3C-5C1824D8C362"
}
]On macOS, addresses are UUIDs (not MAC addresses). This is normal — CoreBluetooth assigns its own identifiers.
3. Set the default address
Paste the address into HUE_LIGHT_ADDRESS in your config and restart Claude Desktop. From then on, you don't need to specify the address in every command.
"env": {
"HUE_LIGHT_ADDRESS": "77577FFA-2F08-CAFD-5F3C-5C1824D8C362"
}How it works
Philips Hue lights broadcast over Bluetooth LE using a proprietary but well-documented GATT profile. This server writes directly to those GATT characteristics using bleak, bypassing the need for a Hue Bridge or the Hue cloud entirely.
Key characteristics used:
UUID | Function |
| Power (on/off) |
| Brightness |
| Color temperature (mireds) |
| XY color (CIE 1931) |
RGB colors are converted to CIE 1931 XY space using the wide RGB D65 gamut matrix before being sent to the light.
Limitations
macOS only — Linux should work too but is untested. Windows is not supported.
Bluetooth range — must be within ~10m of the light.
One adapter per light — the light bonds to the Bluetooth adapter used during first pairing. A different Mac won't be able to connect without re-pairing.
Multiple lights — supported, just call each tool with the specific address. Set
HUE_LIGHT_ADDRESSto your primary light for convenience.
License
MIT
Available Tools
8 toolsget_light_stateA
Read the current state of a Philips Hue light (power, brightness, color mode).
Args: address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: address. Returns: result
scan_hue_lightsA
Scan for Philips Hue BLE lights nearby and return their names and addresses. Run this first to find your light's Bluetooth address — you'll need it for all other tools.
On macOS, addresses look like UUIDs (e.g. 'BEF1AF5D-9A4D-4C2B-8870-1AB7CC5CE8DD'). This is normal — macOS CoreBluetooth uses its own identifiers instead of MAC addresses.
Args: timeout: How many seconds to scan (default 10). Increase if your light isn't found.
Inputs: timeout. Returns: result
set_brightnessA
Set the brightness of a Philips Hue light (turns it on if off).
Args: brightness: Brightness as a percentage, 1–100. address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: brightness (required), address. Returns: result
set_colorA
Set the color of a Philips Hue light using RGB values. Switches the light to color mode. Use set_color_temperature to go back to white mode.
Args: red: Red channel, 0–255 green: Green channel, 0–255 blue: Blue channel, 0–255 address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: red (required), green (required), blue (required), address. Returns: result
set_color_temperatureA
Set the color temperature of a Philips Hue light. Switches the light to white/CT mode (disables any color).
Args: kelvin: Color temperature in Kelvin. 2000K = very warm candlelight 2700K = warm white (typical bulb) 4000K = neutral / office white 6500K = cool daylight address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: kelvin (required), address. Returns: result
set_sceneA
Apply a preset lighting scene to a Philips Hue light.
Available scenes: relax - Dim warm amber, great for winding down energize - Bright cool white, boost alertness concentrate - Bright neutral white, focus mode reading - Warm white at comfortable reading level nightlight - Very dim warm red, minimal sleep disruption bright - Full brightness daylight white
Args: scene: Scene name (case-insensitive) address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: scene (required), address. Returns: result
turn_offA
Turn off a Philips Hue light.
Args: address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: address. Returns: result
turn_onB
Turn on a Philips Hue light.
Args: address: Bluetooth address from scan_hue_lights. Leave blank to use HUE_LIGHT_ADDRESS env var.
Inputs: address. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a distinct, non-overlapping purpose: scanning, state reading, toggling power, setting brightness, color, color temperature, and scenes. No ambiguity in tool selection.
All tools follow a consistent verb_noun pattern in snake_case (e.g., scan_hue_lights, set_brightness, turn_off). No mixing of conventions.
8 tools is well-scoped for controlling a single Hue light via BLE. Each function is necessary and none feel extraneous.
Covers all core operations: discovery, state reading, on/off, brightness, color, color temperature, and preset scenes. No obvious gaps for single-light control.
Maintenance
Related MCP Connectors
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.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables control of Philips Hue lights through Claude and other LLM interfaces using the OpenHue CLI.610MIT
- 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 discovery and control of Philips Hue lighting devices via a local bridge using the CLIP v2 API, without any cloud dependency.10MIT
- AlicenseAqualityBmaintenanceEnables Claude to control Philips Hue lights through a Hue Bridge on the local network, handling plain-language requests for on/off, brightness, color, scenes, looping effects, and whole-room power budgets. Fades and timers run on the bridge itself, and no Hue cloud account is required.9MIT