OpenHue MCP 服务器

一个通过 OpenHue CLI 使用 Claude 及其他 LLM 接口控制飞利浦 Hue 灯光的 MCP 服务器。

前提条件

• Node.js (v16 或更高版本)
• Docker
• Claude for Desktop（可选，用于测试）

桥接设置

在使用服务器之前，你需要用你的 Hue Bridge 设置 OpenHue CLI：

1. 运行设置命令：

# On Linux/macOS:
docker run -v "${HOME}/.openhue:/.openhue" --rm --name=openhue -it openhue/cli setup

# On Windows (PowerShell):
docker run -v "${env:USERPROFILE}\.openhue:/.openhue" --rm --name=openhue -it openhue/cli setup

1. 按照屏幕上的指示操作：

   • CLI 将会搜索你的 Hue Bridge
   • 当提示时按下 Hue Bridge 上的链接按钮
   • 等待确认设置已完成

2. 通过列出你的灯光来验证设置是否成功：

# On Linux/macOS:
docker run -v "${HOME}/.openhue:/.openhue" --rm --name=openhue -it openhue/cli get lights

# On Windows (PowerShell):
docker run -v "${env:USERPROFILE}\.openhue:/.openhue" --rm --name=openhue -it openhue/cli get lights

如果你能看到列出的灯光，那么设置就完成了，你可以开始使用 MCP 服务器了。

安装

1. 克隆仓库：

git clone <your-repo-url>
cd claude-mcp-openhue

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

1. 运行服务器：

npm start

功能

此服务器通过 MCP 暴露以下功能：

灯光控制

• 列出所有灯光或获取特定灯光的详细信息
• 开关灯光
• 调整亮度
• 设置颜色
• 控制色温

房间控制

• 列出所有房间或获取房间详情
• 一起控制房间内的所有灯光
• 设置整个房间的亮度和颜色

场景管理

• 列出可用场景
• 以不同模式激活场景
• 按房间筛选场景

与 Claude Desktop 的使用

1. 打开你的 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加服务器配置：

{
  "mcpServers": {
    "hue": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"]
    }
  }
}

1. 重启 Claude Desktop

2. 查找锤子图标以验证服务器已连接

示例命令

连接后，你可以向 Claude 提出自然语言问题，例如：

• "客厅里有哪些灯？"
• "打开厨房的所有灯"
• "将卧室灯光调到50%亮度"
• "将办公室灯光改为蓝色"
• "激活'放松'场景"
• "休息室有哪些可用场景？"

可用工具

get-lights

列出所有灯光或获取特定灯光的详细信息

{
  lightId?: string;  // Optional light ID or name
  room?: string;     // Optional room name filter
}

control-light

控制单个灯光

{
  target: string;    // Light ID or name
  action: "on" | "off";
  brightness?: number; // 0-100
  color?: string;     // Color name
  temperature?: number; // 153-500 Mirek
}

get-rooms

列出所有房间或获取特定房间的详细信息

{
  roomId?: string;  // Optional room ID or name
}

control-room

控制房间内的所有灯光

{
  target: string;    // Room ID or name
  action: "on" | "off";
  brightness?: number;
  color?: string;
  temperature?: number;
}

get-scenes

列出可用场景

{
  room?: string;    // Optional room name filter
}

activate-scene

激活特定场景

{
  name: string;     // Scene name or ID
  room?: string;    // Optional room name
  mode?: "active" | "dynamic" | "static";
}

开发

项目结构

.
├── src/
│   └── index.ts    # Main server implementation
├── build/          # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

构建

npm run build

运行

npm start

故障排除

服务器无法连接

1. 检查 Docker 是否正在运行
2. 验证 OpenHue 配置是否存在
3. 检查 Claude Desktop 日志
4. 尝试直接运行 OpenHue CLI

命令失败

1. 检查 OpenHue CLI 权限
2. 验证灯光/房间/场景名称
3. 检查 Docker 容器日志
4. 验证 Hue Bridge 连接性

许可证

请注意，原文档中的代码块（如 #0、#1 等）保留不变。这些占位符应替换为实际的命令或配置内容。

MIT 许可

贡献指南

1. Fork 该仓库
2. 创建你的功能分支
3. 提交你的更改
4. 将更改推送到分支
5. 创建一个新的 Pull Request