快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

pip install -r requirements.txt

详细介绍

Philips Hue API v2 MCP服务器

模型上下文协议（MCP）服务器，用于通过API v2。

特性

完全支持API v2：带应用程序密钥身份验证的HTTPS
基于资源的体系结构：访问所有桥梁资源（灯光、房间、场景、传感器）
独立灯光控制：开/关、亮度、色温、XY颜色
房间/区域控制：同时控制多个灯
场景激活：应用保存的照明场景
设备发现：自动发现网络上的网桥
配置管理：使用安装向导进行基于YAML的配置

快速开始

1.安装依赖项

pip install -r requirements.txt

2.初始身份验证设置

运行交互式设置脚本以通过网桥进行身份验证：

python setup_hue_auth.py

流程：

脚本发现网桥IP（或手动输入）
按下网桥上的物理链接按钮
在脚本中按Enter键
生成应用程序密钥并保存到 hue_config.yaml

安全说明： 需要按下链接按钮，以确保只有授权的应用程序才能控制您的灯光。这遵循RFC 7235认证原则。

3.运行MCP服务器

python hue_mcp_server.py

或者添加到Claude Desktop配置：

{
  "mcpServers": {
    "hue-api-v2": {
      "command": "python",
      "args": ["/path/to/hue_mcp_server.py"]
    }
  }
}

配置

配置存储在 hue_config.yaml:

bridge:
  ip: "192.168.1.4"                # Bridge IP address
  api_key: "oG4yy2VTHwIsr2GN5..."  # Application key (40 chars)
  
api:
  version: "v2"                    # API version
  base_path: "/clip/v2"            # API endpoint base
  use_https: true                  # Use HTTPS (required for v2)
  verify_ssl: false                # Bridge uses self-signed cert
  
timeouts:
  request: 10                      # Request timeout (seconds)
  connection: 5                    # Connection timeout (seconds)

API体系结构

端点

API v2通过HTTPS使用基于资源的端点：

Base URL: https://{bridge_ip}/clip/v2
Header:   hue-application-key: {api_key}

资源结构：

/resource -所有资源
/resource/{type} -特定类型的资源
/resource/{type}/{id} -按UUID指定资源

常见操作：

GET -检索资源
PUT -更新资源状态
POST -创建新资源
DELETE -删除资源

资源类型

核心资源：

light -独立灯
scene -保存的照明场景
room -物理房间
zone -自定义灯光区域
grouped_light -组控制端点
device -物理设备（灯泡、开关、传感器）
bridge -桥梁信息

传感器：

motion -运动传感器
temperature -温度传感器
light_level -环境光传感器
contact -接触/门传感器

控制：

button -按钮装置
relative_rotary -旋转/调光器控制

娱乐：

entertainment_configuration -同步娱乐区

可用的MCP工具

设置工具

`hue_setup_authentication`

初始网桥身份验证设置。

参数：

bridge_ip （可选）：网桥IP，留空以进行自动发现
app_name （可选）：应用程序名称（默认：“hue-mcp-server”）

流程：

如果未提供IP，则发现网桥
提示按下链接按钮
生成应用程序密钥
保存到 hue_config.yaml

例子：

{
  "bridge_ip": "192.168.1.4",
  "app_name": "my-hue-app"
}

资源访问工具

`hue_get_resources`

获取所有资源或按类型筛选。

参数：

resource_type （可选）：要过滤的类型（灯光、场景、房间、区域等）

退货： {"data": [...]}

例子：

{"resource_type": "light"}

`hue_get_resource_by_id`

通过UUID获取特定资源。

参数：

resource_type （必填）：资源类型
resource_id （必需）：资源UUID

退货： {"data": [{...}]}

例子：

{
  "resource_type": "light",
  "resource_id": "e706416a-8c92-46ef-8589-3453f3235b13"
}

灯光控制工具

`hue_control_light`

控制单个灯光状态。

参数：

light_id （必需）：轻型UUID
on （可选）：打开/关闭（布尔值）
brightness （可选）：0-100%
color_temperature （可选）：153-500米
color_xy （可选）：CIE xy坐标 {"x": 0.3, "y": 0.3}
transition_time （可选）：持续时间（毫秒）

色温值：

153-mirek=6500K（冷白色）
250-mirek=4000K（中性）
500-mirek=2000K（暖白色）

例子：

{
  "light_id": "e706416a-8c92-46ef-8589-3453f3235b13",
  "on": true,
  "brightness": 75,
  "color_temperature": 300,
  "transition_time": 1000
}

颜色示例：

{
  "light_id": "e706416a-8c92-46ef-8589-3453f3235b13",
  "on": true,
  "color_xy": {"x": 0.3, "y": 0.6}
}

`hue_control_room`

控制房间/区域内的所有灯光。

参数：

room_id （必填）：房间/区域UUID
on （可选）：打开/关闭
brightness （可选）：0-100%
color_temperature （可选）：153-500米

流程：

检索房间 grouped_light 服务
将更改应用于组中的所有灯光

例子：

{
  "room_id": "3f4ac4e9-d67a-4dbd-8a16-5ea7e373f281",
  "on": true,
  "brightness": 50
}

`hue_activate_scene`

激活已保存的场景。

参数：

scene_id （必需）：场景UUID

例子：

{"scene_id": "9de116fc-5fd2-4b74-8414-0f30cb2cbe04"}

信息工具

`hue_list_lights_detailed`

获取全面的灯光信息。

退货： 灯阵列具有：

id -轻型UUID
name -设备名称
type -灯光类型
on -当前状态
brightness -当前亮度
color_temp_mirek -当前色温
color_xy -当前颜色坐标
reachable -连接状态
rooms -指定房间
model -产品型号

例子：

[
  {
    "id": "e706416a-8c92-46ef-8589-3453f3235b13",
    "name": "Living Room Lamp",
    "type": "light",
    "on": true,
    "brightness": 75.0,
    "color_temp_mirek": 300,
    "color_xy": {
      "x": 0.3,
      "y": 0.3
    },
    "reachable": true,
    "rooms": ["Living Room"],
    "model": "Hue color lamp"
  },
  {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "Office Desk",
    "type": "light",
    "on": false,
    "brightness": null,
    "color_temp_mirek": null,
    "color_xy": null,
    "reachable": true,
    "rooms": ["Office"],
    "model": "Hue white lamp"
  }
]

`hue_search_by_name`

按名称搜索资源。

参数：

name （必填）：搜索词（不区分大小写）
resource_type （可选）：按类型筛选

退货： 匹配资源数组

例子：

{
  "name": "living",
  "resource_type": "light"
}

测试

测试脚本

运行bash测试脚本以验证连接：

./test_hue_api.sh

测验：

获取所有灯光
获取所有房间
获取所有场景
获取桥梁信息
获取设备

手动测试

# Get all lights
curl --insecure \
  -H "hue-application-key: YOUR_KEY" \
  https://192.168.1.4/clip/v2/resource/light

# Turn on a light
curl --insecure -X PUT \
  -H "hue-application-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on":{"on":true},"dimming":{"brightness":75}}' \
  https://192.168.1.4/clip/v2/resource/light/LIGHT_ID

API v2关键概念

认证

初始设置：

按下网桥上的物理链接按钮
张贴到 https://{bridge_ip}/api 设备类型
接收应用程序密钥（40个字符的十六进制字符串）
使用密钥 hue-application-key 所有请求的标头

安全： 应用程序密钥验证所有API请求。保持安全。

资源模型

API v2使用基于资源的模型，其中：

一切都是具有UUID的资源
资源具有类型和属性
资源可以引用其他资源
更改通过资源关系传播

示例资源：

{
  "id": "e706416a-8c92-46ef-8589-3453f3235b13",
  "type": "light",
  "on": {"on": true},
  "dimming": {"brightness": 75.0},
  "color_temperature": {"mirek": 300},
  "owner": {
    "rid": "3f4ac4e9-d67a-4dbd-8a16-5ea7e373f281",
    "rtype": "device"
  }
}

状态更新

有效载荷结构：

{
  "on": {"on": true},                        // Power state
  "dimming": {"brightness": 75.0},           // Brightness (0-100%)
  "color_temperature": {"mirek": 300},       // Color temp
  "color": {"xy": {"x": 0.3, "y": 0.3}},     // Color
  "dynamics": {"duration": 1000}             // Transition time (ms)
}

多个属性： 您可以在一个请求中更新多个属性。

房间与分组灯

房间：元数据和服务的逻辑分组
分组灯：房间/区域中灯光的控制端点

访问模式：

获取房间资源
找到 grouped_light 客房服务阵列中的服务
使用grouped_light UUID进行控制操作

代码文档

函数参考

配置功能：

load_config() -加载YAML配置
save_config(config) -保存YAML配置
get_base_url() -构造API基础URL

身份验证功能：

discover_bridge() -自动发现网桥IP
authenticate_bridge(ip, app_name) -生成应用程序密钥

API函数：

make_request(method, endpoint, data) -使用身份验证执行HTTP请求

错误处理

常见错误：

101 -链接按钮未按下
403 -未经授权（无效的应用程序密钥）
404 -未找到资源
500 -桥接错误

连接问题：

验证网桥IP地址
检查网络连接
确保使用HTTPS（API v2要求）
网桥可能需要更新API v2的固件

参考文献

故障排除

未发现桥梁：

确保网桥已连接到网络
网桥最初必须有互联网接入
尝试手动输入IP

身份验证失败：

在验证之前立即按下链接按钮
链接按钮超时30秒
每次按下按钮仅尝试一次身份验证

SSL证书错误：

Bridge使用自签名证书
verify_ssl: false 在配置中是必需的
这是正常的，也是意料之中的

灯光控制不工作：

验证灯光UUID是否正确
检查灯是否可用（未关闭电源）
确保颜色/亮度值在有效范围内
某些属性仅适用于某些灯光类型

许可证

该项目根据CC BY-NC-SA 4.0获得许可-见许可证.md

商业用途

如需商业许可咨询，请联系：\[mave at cero32-dot cl\]

商业用途包括：

在付费产品或服务中使用此功能
将其作为SaaS平台的一部分提供
将其包含在专有软件中
利用这一点来产生收入

目录标签

智能家居PythonClaude物联网本地部署灯光控制API服务自动化

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

工具数量（toolCount，工具数）

8

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/8f778802c1adf421ce67c97bd5bc79cd

Philips Hue API v2 MCP服务器提供对Hue灯光的全面控制功能，包括单个灯光控制、房间/区域控制、场景激活等，适用于智能家居和自动化场景。

继续浏览同类 MCP

更多浏览器工具 MCP（2,803）返回 MCP 目录

上一个 MCP

Phact MCP

全面解析MCP Browser Use ToolsMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器，MCP Browser Use Tools能让AI助手访问实时数据、执行操作，为您提供更智能的工作体验和自动化解决方案。

下一个 MCP

Php 3e0f007f

全面解析Php Universal MCP ServerMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器，Php Universal MCP Server能让AI助手访问实时数据、执行操作，为您提供更智能的工作体验和自动化解决方案。

philips hue MCP server apiv2

快速接入

详细介绍

Philips Hue API v2 MCP服务器

特性

快速开始

1.安装依赖项

2.初始身份验证设置

3.运行MCP服务器

配置

API体系结构

端点

资源类型

可用的MCP工具

设置工具

hue_setup_authentication

资源访问工具

hue_get_resources

hue_get_resource_by_id

灯光控制工具

hue_control_light

hue_control_room

hue_activate_scene

信息工具

hue_list_lights_detailed

hue_search_by_name

测试

测试脚本

手动测试

API v2关键概念

认证

资源模型

状态更新

房间与分组灯

代码文档

函数参考

错误处理

参考文献

故障排除

许可证

商业用途

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`hue_setup_authentication`

`hue_get_resources`

`hue_get_resource_by_id`

`hue_control_light`

`hue_control_room`

`hue_activate_scene`

`hue_list_lights_detailed`

`hue_search_by_name`