hue-ble-mcp 0.1.0

MCP server to control Philips Hue lights via Bluetooth LE — no bridge required

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
scan_hue_lights	Discover nearby Hue BLE lights and get their addresses
turn_on	Turn a light on
turn_off	Turn a light off
set_brightness	Set brightness 1–100%
set_color_temperature	Set white color temperature (2000K warm → 6500K cool)
set_color	Set RGB color
get_light_state	Read current power, brightness, and color mode
set_scene	Apply a preset: relax, energize, concentrate, reading, nightlight, bright

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-mcp

Then 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.txt

Then 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
932c32bd-0002-...	Power (on/off)
932c32bd-0003-...	Brightness
932c32bd-0004-...	Color temperature (mireds)
932c32bd-0005-...	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_ADDRESS to your primary light for convenience.

License

MIT