Hue BLE MCP

hue-ble-mcp

一个 MCP 服务，可让 Claude 通过 Bluetooth LE 控制 Philips Hue 灯具，无需 Hue Bridge 或互联网连接。

只需向 Claude 提出以下请求：

• “关掉灯”
• “将灯设置为温暖的阅读模式”
• “调成深蓝色”
• “调暗到 20%”

工具

工具	描述
scan_hue_lights	搜索附近的 Hue BLE 灯具并获取其地址
turn_on	打开灯
turn_off	关闭灯
set_brightness	设置亮度为 1–100%
set_color_temperature	设置白光色温（2000K 暖光 → 6500K 冷光）
set_color	设置 RGB 颜色
get_light_state	读取当前电源状态、亮度和颜色模式
set_scene	应用预设场景：relax、energize、concentrate、reading、nightlight、bright

要求

• macOS（通过 bleak 使用 CoreBluetooth）
• Python 3.10+
• 支持 Bluetooth 的 Philips Hue 灯具（大多数 2019 年后生产的灯具）
• Claude Desktop

安装

选项 1：pip（推荐）

pip install hue-ble-mcp

然后将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "hue-ble": {
      "command": "hue-ble-mcp",
      "env": {
        "HUE_LIGHT_ADDRESS": ""
      }
    }
  }
}

选项 2：克隆并运行

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

然后将以下内容添加到 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": ""
      }
    }
  }
}

首次设置

1. 配对灯具

Hue BLE 灯具首次连接时需要处于配对模式。最简单的方式是通过 Hue 应用重置灯具（Settings → Light setup → 选择灯具 → Delete），使其恢复出厂配对模式。

首次成功连接后，macOS 会记住配对信息，之后无需再进行此操作。

2. 查找灯具地址

重启 Claude Desktop，然后询问：

“扫描我的 Hue 灯具”

Claude 会返回类似以下内容：

[
  {
    "name": "Signe gradient floor",
    "address": "77577FFA-2F08-CAFD-5F3C-5C1824D8C362"
  }
]

在 macOS 上，地址是 UUID（而非 MAC 地址）。这是正常现象，CoreBluetooth 会分配自己的标识符。

3. 设置默认地址

将地址粘贴到配置中的 HUE_LIGHT_ADDRESS，然后重启 Claude Desktop。此后，每条命令都无需指定地址。

"env": {
  "HUE_LIGHT_ADDRESS": "77577FFA-2F08-CAFD-5F3C-5C1824D8C362"
}

工作原理

Philips Hue 灯具通过 Bluetooth LE 广播，并使用专有但有详细文档的 GATT 配置文件。此服务使用 bleak 直接写入这些 GATT 特征，无需 Hue Bridge 或 Hue 云服务。

使用的主要特征：

UUID	功能
932c32bd-0002-...	电源（开/关）
932c32bd-0003-...	亮度
932c32bd-0004-...	色温（mired）
932c32bd-0005-...	XY 颜色（CIE 1931）

发送到灯具之前，RGB 颜色会通过宽色域 RGB D65 矩阵转换为 CIE 1931 XY 色彩空间。

限制

• 仅限 macOS —— Linux 应该也能运行，但未经测试。不支持 Windows。
• Bluetooth 范围 —— 必须位于灯具约 10 米范围内。
• 每盏灯具仅限一个适配器 —— 灯具会与首次配对时使用的 Bluetooth 适配器绑定。若不重新配对，其他 Mac 将无法连接。
• 多盏灯具 —— 支持，只需为每个工具调用指定对应地址。为方便起见，可将 HUE_LIGHT_ADDRESS 设置为主灯具的地址。

许可证

MIT