lifx-api-mcp服务器

Name: lifx-api-mcp服务器
Author: furey

作者：furey3 星标更新：2025-04-21

安装使用来源：spider==github.com

项目介绍

LIFX API MCP Server

LIFX API MCP Server 是一个本地模型上下文协议（MCP）服务器，通过大型语言模型（LLMs）使用自然语言访问LIFX设备，执行诸如列出灯光、设置状态、激活场景和触发效果等操作。包括上下文资源和有用的提示。

快速开始

获取LIFX API令牌：
- 前往你的LIFX云设置页面。
- 生成一个新的个人访问令牌。请确保安全保管此令牌！

安装LIFX MCP服务器： （选择一种方法）

NPX（推荐）：
```
npx -y lifx-api-mcp-server@latest
```

Docker：

docker run --rm -i --network=host --pull=always furey/lifx-api-mcp-server

配置API令牌：
- 关键步骤： 通过以下任一方法设置您的令牌（优先顺序）：
  1. 配置文件（推荐）： 编辑 ~/.lifx-api-mcp-server.jsonc（使用 npx -y lifx-api-mcp-server@latest config:create 生成），并在 apiToken 字段中添加您的令牌。
  2. 环境变量： 设置 CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN。
  3. 命令行参数（最不推荐）： 在运行服务器时传递令牌（例如，npx ... YOUR_TOKEN）。
设置MCP客户端：
- 配置您的客户端（例如，Claude Desktop，MCP Inspector），如果使用配置/环境变量，则在启动服务器时不传递令牌参数。
控制您的灯光：
- 开始使用自然语言与您的LIFX设备互动（参见教程）。使用资源如 @lix-api:lifx://lights 和提示如 @lix-api:effect-creator。

特性

工具

list-lights: 获取属于账户的灯光，可通过选择器过滤。
set-state: 设置所选灯光的状态（电源、颜色、亮度等）。
set-states: 在一次请求中设置多个选择器的多个状态。
state-delta: 改变状态属性（亮度、色相、饱和度、开尔文温度、红外线）的相对值。
toggle-power: 切换所选灯光的电源状态。
breathe-effect: 执行呼吸（渐变）效果。
pulse-effect: 执行脉冲（闪光）效果。
move-effect: 对线性设备（LIFX Z条带）执行移动效果。
morph-effect: 对Tile设备执行变形效果。
flame-effect: 对Tile设备执行火焰效果。
clouds-effect: 对Tile设备执行云朵效果（固件版本>=4.8）。
sunrise-effect: 对Tile设备执行日出效果（固件版本>=4.8）。
sunset-effect: 对Tile设备执行日落效果（固件版本>=4.8）。
effects-off: 关闭任何正在运行的效果。
list-scenes: 列出账户中的可用场景。
activate-scene: 根据UUID激活指定场景。
cycle: 循环所选灯光通过预定义状态列表。
validate-color: 验证颜色字符串并返回其组成部分。
clean: 控制LIFX清洁设备。

资源

lifx://lights: 提供可用灯光的摘要列表（ID、标签、电源、连接状态）。获取实时数据。
lifx://light/{selector}/state: 提供匹配选择器的灯光的详细当前状态。支持选择器的自动补全。获取实时数据。
lifx://scenes: 提供可用场景的列表（名称、UUID）。获取实时数据。

提示

effect-creator: 引导用户创建效果参数，并生成相应的工具命令。
troubleshooter: 通过检查特定灯光的状态来诊断基本的连接问题（获取实时数据）。
selector-helper: 列出从实时数据中获取的可用标识符（标签、组、位置、ID），帮助用户构建准确的选择器。

其他特性

配置文件： 通过 ~/.lifx-api-mcp-server.jsonc 自定义设置。
环境变量： 覆盖配置设置（例如，CONFIG_API_TOKEN，CONFIG_LOG_LEVEL）。
组件禁用： 通过配置选择性地禁用工具、资源或提示。
直接API映射： 工具通常与LIFX API端点一对一对应。
错误处理： 根据LIFX API响应和HTTP状态码提供反馈。
选择器支持： 使用LIFX选择器（all，id:，label: 等）来定位灯光。
颜色支持： 接受标准的LIFX颜色字符串。
Docker支持： 在Docker容器内轻松运行。

安装

LIFX MCP服务器可以通过多种方式安装和运行：

NPX（最简单）
Docker Hub
从源代码安装Node.js
从源代码安装Docker

安装：NPX

[!NOTE] NPX需要安装Node.js（v18+）。

# 确保已安装Node.js v18+
node --version

# 运行服务器（建议通过配置/环境变量设置令牌）
npx -y lifx-api-mcp-server@latest [YOUR_LIFX_API_TOKEN_IF_NEEDED]

安装：Docker Hub

[!NOTE] 需要安装Docker。

# 确保已安装Docker
docker --version

# 运行服务器（建议通过配置/环境变量设置令牌）
# 挂载配置文件（推荐）：
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lLIFX_API_MCP_SERVER.jsonc:ro \
  --pull=always furey/lifx-api-mcp-server

# 或者通过环境变量传递令牌：
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  --pull=always furey/lifx-api-mcp-server

# 或者作为参数传递令牌（最不推荐）：
docker run --rm -i --network=host \
  --pull=always furey/lifx-api-mcp-server YOUR_LIFX_API_TOKEN

(如果不同，请替换furey/lifx-api-mcp-server为实际的Docker Hub镜像名称)

安装：从源代码安装Node.js

[!NOTE] 需要安装Node.js（v18+）和npm/yarn。

克隆仓库（如果发布，请替换为实际URL）：

git clone https://github.com/furey/lifx-api-mcp-server.git # 占位符
cd lifx-api-mcp-server

安装依赖项：
```
npm install
```
运行服务器（建议通过配置/环境变量设置令牌）：
```
node lifx-api-mcp-server.js [YOUR_LIFX_API_TOKEN_IF_NEEDED]
```

安装：从源代码安装Docker

[!NOTE] 需要安装Docker。

克隆仓库：

git clone https://github.com/furey/lifx-api-mcp-server.git # 占位符
cd lifx-api-mcp-server

构建Docker镜像：
```
docker build -t lifx-mcp-server .
```

运行容器（建议通过配置/环境变量设置令牌）：

# 使用挂载的配置文件（推荐）：
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  lifx-mcp-server

# 使用环境变量：
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  lifx-mcp-server

# 使用参数（最不推荐）：
docker run --rm -i --network=host \
  lifx-mcp-server YOUR_LIFX_API_TOKEN

安装验证

当服务器成功启动时，您应该看到如下输出：

[LIFX MCP] LIFX API MCP Server vX.Y.Z 正在启动...
[LIFX MCP] 加载配置文件：/path/to/.lifx-api-mcp-server.jsonc（或“未找到配置文件”）
[LIFX MCP] 初始化MCP服务器...
[LIFX MCP] 注册MCP资源...
[LIFX MCP] 注册的MCP资源总数：X
[LIFX MCP] 注册MCP提示...
[LIFX MCP] 注册的MCP提示总数：Y
[LIFX MCP] 注册MCP工具...
[LIFX MCP] 注册的MCP工具总数：Z
[LIFX MCP] 创建stdio传输...
[LIFX MCP] 连接MCP服务器传输...
[LIFX MCP] LIFX API MCP Server 正在运行。

配置

通过配置文件或环境变量自定义服务器的行为。API令牌是最关键的设置。

配置：API令牌（优先顺序）

配置文件（apiToken键）： 创建/编辑 ~/.lifx-api-mcp-server.jsonc。（推荐）
环境变量（CONFIG_API_TOKEN）： 设置 CONFIG_API_TOKEN=YOUR_TOKEN。
命令行参数： 在运行脚本时传递令牌作为第一个参数。（最不推荐）

配置：配置文件

在 ~/.lifx-api-mcp-server.jsonc（或 .json）创建配置文件。使用 npx -y lifx-api-mcp-server@latest config:create 生成它。

<details> <summary>示例配置文件（`~/.lifx-api-mcp-server.jsonc`）</summary>

{
  // 您的LIFX个人访问令牌（如果未使用ENV或CLI参数则必需）
  // 获取自：https://cloud.lifx.com/settings
  "apiToken": "YOUR_LIFX_API_TOKEN_HERE",

  // 日志级别："info"（默认）或"verbose"以获得更详细的日志，包括速率限制信息
  "logLevel": "info",

  // --- 可选：禁用特定组件 ---
  // 在这里添加组件名称以禁用它们。示例：
  // "disabled": {
  //   "tools": ["clean", "cycle"], // 禁用特定工具
  //   "resources": ["scenes"],     // 禁用场景资源
  //   "prompts": true              // 禁用所有提示
  // },
  "disabled": {
    "tools": [],
    "resources": [],
    "prompts": []
  },

  // --- 可选：仅启用特定组件 ---
  // 如果定义了“enabled”数组，则仅启用这些类型的组件，
  // 覆盖该类型的所有“disabled”设置。示例：
  // "enabled": {
  //    "tools": ["list-lights", "set-state"], // 仅启用这两个工具
  //    "resources": ["lights"]                // 仅启用灯光资源
  // }
  "enabled": {
    "tools": null,
    "resources": null,
    "prompts": null
  }
}

</details>

配置：配置文件生成

您可以自动生成默认配置文件：

# NPX使用（推荐）
npx -y lifx-api-mcp-server@latest config:create

# Node.js使用（从源目录）
npm run config:create

# 强制覆盖现有文件
npx -y lifx-api-mcp-server@latest config:create -- --force
npm run config:create -- --force

# 指定自定义路径/文件名（使用CONFIG_PATH环境变量）
CONFIG_PATH=/path/to/my-lifx-config.jsonc npm run config:create

这会将示例配置内容保存到默认的 ~/.lifx-api-mcp-server.jsonc。

配置：环境变量覆盖

设置可以使用环境变量覆盖（优先于配置文件）。

配置设置	环境变量覆盖	示例值
`apiToken`	`CONFIG_API_TOKEN`	`c0ffee...`
`logLevel`	`CONFIG_LOG_LEVEL`	`verbose`
`disabled.tools`	`CONFIG_DISABLED_TOOLS`	`clean,cycle` / `true`
`enabled.tools`	`CONFIG_ENABLED_TOOLS`	`list-lights,set-state`
`disabled.resources`	`CONFIG_DISABLED_RESOURCES`	`scenes` / `true`
`enabled.resources`	`CONFIG_ENABLED_RESOURCES`	`lights,light-state`
`disabled.prompts`	`CONFIG_DISABLED_PROMPTS`	`troubleshooter` / `true`
`enabled.prompts`	`CONFIG_ENABLED_PROMPTS`	`effect-creator`

示例用法：

# 使用环境变量设置令牌和日志级别时使用NPX
CONFIG_API_TOKEN=YOUR_TOKEN CONFIG_LOG_LEVEL=verbose npx -y lifx-api-mcp-server@latest

# 同样的例子使用Docker
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_TOKEN \
  -e CONFIG_LOG_LEVEL=verbose \
  --pull=always furey/lifx-api-mcp-server

客户端设置

配置您的MCP客户端（例如，Claude Desktop，MCP Inspector）以启动 lifx-api-mcp-server。重要： 如果您已通过配置文件或环境变量设置了API令牌，则在客户端设置中不要将其作为参数传递。

客户端设置：Claude Desktop

安装Claude Desktop。
查找或创建 claude_desktop_config.json：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

添加服务器配置（根据需要调整路径）：

{
  "mcpServers": {
    "lix-api": {
      // 如果不在默认PATH中，请使用完整的npx路径
      "command": "/path/to/your/npx", // 或node
      "args": [
        // NPX示例：（如果在配置/环境变量中设置了令牌，则此处不需要令牌）
        "-y",
        "lifx-api-mcp-server@latest"

        // 从源代码安装Node.js示例：（如果在配置/环境变量中设置了令牌，则此处不需要令牌）
        // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
      ],
      "env": {
         // 可选：取消注释以启用详细日志
         // "CONFIG_LOG_LEVEL": "verbose"
         // 可选：如果未使用配置文件，则通过环境变量设置令牌
         // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
      }
    }
  }
}

重启Claude Desktop。
开始聊天并尝试与您的灯光互动（例如，“@lix-api 列出我的灯光”）。

客户端设置：MCP Inspector

MCP Inspector 对调试很有帮助。

# 使用LIFX服务器运行MCP Inspector（如果在配置/环境变量中设置了令牌，则此处不需要令牌）
npx -y @modelcontext