Skip to main content
Glama
io.github.jonnyblankinship/hue-ble-mcp

io.github.jonnyblankinship/hue-ble-mcp

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

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

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

Available Tools

8 tools
get_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

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., scan_hue_lights, set_brightness, turn_off). No mixing of conventions.

    Tool Count5/5

    8 tools is well-scoped for controlling a single Hue light via BLE. Each function is necessary and none feel extraneous.

    Completeness5/5

    Covers all core operations: discovery, state reading, on/off, brightness, color, color temperature, and preset scenes. No obvious gaps for single-light control.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control Philips Hue smart lighting systems, including individual lights, groups, scenes, brightness, and color adjustments through natural language commands.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables discovery and control of Philips Hue lighting devices via a local bridge using the CLIP v2 API, without any cloud dependency.
      10
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      9
      MIT