LIFX API MCP Server

LIFX API MCP Server

LIFX API MCP Server 是一个本地 MCP（模型上下文协议）服务，可通过 LLM 使用自然语言访问 LIFX 设备，并通过 LIFX HTTP API 执行列出灯具、设置状态、激活场景和触发效果等操作。它还提供上下文资源和实用提示词。

目录

• 快速开始
• 功能
• 安装
• 配置
• 客户端设置
• 数据保护
• 教程
• Dockerfile
• 免责声明
• 支持

快速开始

1. 获取 LIFX API 令牌：
   • 前往 LIFX Cloud 设置页面。
   • 生成新的个人访问令牌。请妥善保管此令牌！
2. 安装 LIFX MCP Server：（选择一种方式）
   • NPX（推荐）：

     npx -y lifx-api-mcp-server@latest
     

   • Docker：

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

3. 配置 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）。
4. 设置 MCP 客户端：
   • 配置客户端（例如，Claude Desktop、MCP Inspector）启动服务；若使用配置文件或环境变量，请勿传入令牌参数。
5. 控制灯具：
   • 使用自然语言开始与 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 设备上执行云朵效果（FW >= 4.8）。
• sunrise-effect：在 Tile 设备上执行日出效果（FW >= 4.8）。
• sunset-effect：在 Tile 设备上执行日落效果（FW >= 4.8）。
• effects-off：关闭所有正在运行的效果。
• list-scenes：列出账户中可用的场景。
• activate-scene：通过 UUID 激活指定场景。
• cycle：让所选灯具按顺序循环显示预定义状态。
• validate-color：验证颜色字符串并返回其组成部分。
• clean：控制 LIFX Clean 设备。

资源

• 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 Server 可以通过多种方式安装和运行：

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

安装：NPX

说明

需要安装 Node.js（v18+）。

# Ensure Node.js v18+ is installed
node --version

# Run the server (token should ideally be set via config/env)
npx -y lifx-api-mcp-server@latest [YOUR_LIFX_API_TOKEN_IF_NEEDED]

安装：Docker Hub

说明

需要安装 Docker。

# Ensure Docker is installed
docker --version

# Run the server (token should ideally be set via config/env)
# Mount config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  --pull=always furey/lifx-api-mcp-server

# OR pass token via environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  --pull=always furey/lifx-api-mcp-server

# OR pass token as argument (least recommended):
docker run --rm -i --network=host \
  --pull=always furey/lifx-api-mcp-server YOUR_LIFX_API_TOKEN

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

安装：从源码安装 Node.js

说明

需要安装 Node.js（v18+）以及 npm/yarn。

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

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

2. 安装依赖：

   npm install
   

3. 运行服务（建议通过配置/环境变量设置令牌）：

   node lifx-api-mcp-server.js [YOUR_LIFX_API_TOKEN_IF_NEEDED]
   

安装：从源码构建 Docker

说明

需要安装 Docker。

1. 克隆仓库：

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

2. 构建 Docker 镜像：

   docker build -t lifx-mcp-server .
   

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

   # 使用挂载的配置文件（推荐）：
   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 starting…
[LIFX MCP] Loading config file: /path/to/.lifx-api-mcp-server.jsonc (or 'No config file found')
[LIFX MCP] Initializing MCP server…
[LIFX MCP] Registering MCP resources…
[LIFX MCP] Total MCP resources registered: X
[LIFX MCP] Registering MCP prompts…
[LIFX MCP] Total MCP prompts registered: Y
[LIFX MCP] Registering MCP tools…
[LIFX MCP] Total MCP tools registered: Z
[LIFX MCP] Creating stdio transport…
[LIFX MCP] Connecting MCP server transport…
[LIFX MCP] LIFX API MCP Server running.

配置

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

配置：API Token（优先级顺序）

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

配置：配置文件

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

{
  // Your LIFX Personal Access Token (Required if not using ENV or CLI arg)
  // Get from: https://cloud.lifx.com/settings
  "apiToken": "YOUR_LIFX_API_TOKEN_HERE",

  // Log level: "info" (default) or "verbose" for more detailed logs including rate limits
  "logLevel": "info",

  // --- Optional: Disable specific components ---
  // Add component names here to disable them. Examples:
  // "disabled": {
  //   "tools": ["clean", "cycle"], // Disable specific tools
  //   "resources": ["scenes"],     // Disable the scenes resource
  //   "prompts": true              // Disable all prompts
  // },
  "disabled": {
    "tools": [],
    "resources": [],
    "prompts": []
  },

  // --- Optional: Enable only specific components ---
  // If an 'enabled' array is defined, ONLY those components of that type will be enabled,
  // overriding any 'disabled' settings for that type. Examples:
  // "enabled": {
  //    "tools": ["list-lights", "set-state"], // Only enable these two tools
  //    "resources": ["lights"]                // Only enable the lights resource
  // }
  "enabled": {
    "tools": null,
    "resources": null,
    "prompts": null
  }
}

配置：生成配置文件

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

# NPX Usage (recommended)
npx -y lifx-api-mcp-server@latest config:create

# Node.js Usage (from source directory)
npm run config:create

# Force overwrite existing file
npx -y lifx-api-mcp-server@latest config:create -- --force
npm run config:create -- --force

# Specify custom path/filename (uses CONFIG_PATH env var)
CONFIG_PATH=/path/to/my-lifx-config.jsonc npm run config:create

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

配置：环境变量覆盖

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

使用示例：

# Set token and log level via environment variables when using NPX
CONFIG_API_TOKEN=YOUR_TOKEN CONFIG_LOG_LEVEL=verbose npx -y lifx-api-mcp-server@latest

# Same example using 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 Token，请勿在客户端设置中将其作为参数传入。

客户端设置：Claude Desktop

1. 安装 Claude Desktop。

2. 找到或创建 claude_desktop_config.json：

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

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

   {
     "mcpServers": {
       "lix-api": {
         // 如果 npx 不在默认 PATH 中，请使用它的完整路径
         "command": "/path/to/your/npx", // 或 node
         "args": [
           // NPX 示例：（如果已在配置文件/环境变量中设置，则此处不填 Token）
           "-y",
           "lifx-api-mcp-server@latest"
   
           // 从源码运行 Node.js 的示例：（如果已在配置文件/环境变量中设置，则此处不填 Token）
           // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
         ],
         "env": {
            // 可选：取消注释以启用详细日志
            // "CONFIG_LOG_LEVEL": "verbose"
            // 可选：如果未使用配置文件，可通过环境变量设置 Token
            // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
         }
       }
     }
   }
   

4. 重启 Claude Desktop。

5. 开始聊天并尝试与灯具交互（例如，“@lix-api 列出我的灯具”）。

客户端设置：MCP Inspector

MCP Inspector 可用于调试。

# Run MCP Inspector with the LIFX server (NO TOKEN HERE if set in config/env)
npx -y @modelcontextprotocol/inspector npx -y lifx-api-mcp-server@latest

# Open the inspector in your browser (usually http://localhost:5173)

数据保护

• API 令牌安全： 您的 LIFX API 令牌可以控制您的灯具。请妥善保密。 使用配置文件（~/.lifx-api-mcp-server.jsonc，并设置适当的文件权限）或环境变量，比将令牌作为命令行参数传递更安全，尤其是在共享环境或日志中。
• 数据流： 使用远程大模型（例如通过 Claude Desktop）时，您发送给大模型的提示词以及此 MCP 服务返回的结果（灯具名称、状态、场景名称）都会发送给大模型提供商。如果隐私是您主要关心的问题，请留意灯具／组／位置／场景标签中可能包含的敏感信息。
• 本地执行： 此服务在您的计算机上本地运行，并通过 HTTPS 直接与 LIFX 云 API 通信。

教程

确保服务正在运行，并已连接到您的 MCP 客户端。将 label:MyLamp 之类的占位符替换为您实际的灯具／组／位置标签或 ID。

1. 查看可用灯具（资源）：

   • @lix-api:lifx://lights
   • ^{➥ 使用 lights 资源}

2. 获取指定灯具状态（资源）：

   • @lix-api:lifx://light/label:Office Lamp/state
   • ^{➥ 使用 light-state 资源}

3. 获取可用场景（资源）：

   • @lix-api:lifx://scenes
   • ^{➥ 使用 scenes 资源}

4. 使用选择器助手（提示词）：

   • @lix-api:selector-helper goal: "the lights in the kitchen"
   • ^{➥ 使用 selector-helper 提示词}

5. 创建效果（提示词）：

   • @lix-api:effect-creator effect_type:breathe selector:all description:"a very slow fade to warm white"
   • ^{➥ 使用 effect-creator 提示词（请遵循响应中的说明）}

6. 排查灯具问题（提示词）：

   • @lix-api:troubleshooter selector:"id:d073d5xxxxxx"
   • ^{➥ 使用 troubleshooter 提示词}

7. 列出您的灯具（工具）：

   • "列出我的灯具" 或 "list lights selector:all"
   • ^{➥ 使用 list-lights 工具}

8. 打开灯具（工具）：

   • "打开名为 Office Lamp 的灯" 或 "set state selector:label:Office Lamp power:on"
   • ^{➥ 使用 set-state 工具}

9. 设置颜色和亮度（工具）：

   • "将 Kitchen 组的灯设为蓝色，亮度为 50%，用时 3 秒"
   • "set state selector:group:Kitchen color:blue brightness:0.5 duration:3"
   • ^{➥ 使用 set-state 工具}

10. 切换某个位置的灯具状态（工具）：

    • "切换 Living Room 的灯具状态" 或 "toggle power selector:location:Living Room"
    • ^{➥ 使用 toggle-power 工具}

11. 提高亮度（工具）：

    • "将所有灯具的亮度提高 10%" 或 "state delta selector:all brightness:0.1"
    • ^{➥ 使用 state-delta 工具}

12. 启用场景（需要从资源／工具获取场景 UUID）：

    • "使用 uuid abcdef12-3456-... 启用场景"
    • "activate scene scene_uuid:abcdef12-3456-..."
    • ^{➥ 使用 activate-scene 工具}

Dockerfile

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies cleanly
# Using --omit=dev because devDependencies are not needed in production
RUN npm ci --omit=dev --production --no-fund --no-audit

# Copy the rest of the application code
COPY . .

# Set the entrypoint
ENTRYPOINT ["node", "lifx-api-mcp-server.js"]

# Default command (can be overridden, e.g., with API token if not using config/env)
# CMD ["YOUR_DEFAULT_TOKEN_IF_NEEDED"]

免责声明

• 本软件按“原样”提供，不提供任何形式的保证。使用风险由您自行承担。
• 作者与 LIFX（LiFi Labs Inc.）无关联。
• 请了解 LIFX API 的速率限制（每个令牌每分钟 120 次请求），以避免遭到临时封锁。如果 logLevel 为 verbose，日志中会记录速率限制信息。
• 此服务部分由 AI 辅助生成，可能存在错误。

支持

如果您觉得此工具有用，可以考虑支持开发者（可选）：

请我喝杯咖啡 | GitHub 赞助