Lifx API MCP Server

LIFX API MCP服务器

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

目录

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

快速开始

1. 获取LIFX API代币：

- 去你的 LIFX云设置页面. - 生成新的个人访问令牌。 请确保此令牌安全！

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

- NPX（推荐）：

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

- Docker：

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

1. 配置API令牌：

- 关键步骤： 通过设置您的令牌 一 这些方法（优先级顺序）： 1. 配置文件（推荐）： 编辑 ~/.lifx-api-mcp-server.jsonc （生成 npx -y lifx-api-mcp-server@latest config:create)并将您的令牌添加到 apiToken 现场。 1. 环境变量： 集 CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN. 1. 命令行参数（最不推荐）： 在运行服务器时传递令牌（例如。， npx ... YOUR_TOKEN).

1. 设置MCP客户端：

- 配置您的客户端（例如。， 克劳德桌面, MCP检查员)启动服务器 *没有* 如果使用config/env，则使用token参数。

1. 控制灯光：

- 开始使用自然语言与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：对磁贴设备执行变形效果。
• flame-effect：在Tile设备上执行火焰效果。
• clouds-effect：在磁贴设备上执行云效果（FW>=4.8）。
• sunrise-effect：在磁贴设备上执行日出效果（FW>=4.8）。
• sunset-effect：在磁贴设备上执行日落效果（FW>=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端点1:1对应。
• 错误处理： 根据LIFX API响应和HTTP状态代码提供反馈。
• 选择器支持： 使用LIFX选择器(all, id:, label:等等）用于瞄准光。
• 颜色支持： 接受标准LIFX颜色字符串。
• Docker支持： 在Docker容器中轻松运行。

安装

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

• NPX （最简单）

安装：NPX

\[！注意\]

NPX要求 （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

\[！注意\]

需要 码头工人 安装。

# 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

*（替换 furey/lifx-api-mcp-server 如果不同，请使用实际的Docker Hub映像名称）*

安装：Node.js源代码

\[！注意\]

需要 安装了（v18+）和npm/yarn。

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

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

1. 安装依赖项：

   npm install

1. 运行服务器（令牌最好通过config/env设置）：

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

安装：Docker源代码

\[！注意\]

需要 码头工人 安装。

1. 克隆存储库：

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

1. 构建Docker镜像：

   docker build -t lifx-mcp-server .

1. 运行容器（令牌最好通过config/env设置）：

   # Using mounted config file (recommended):
   docker run --rm -i --network=host \
     -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
     lifx-mcp-server

   # Using environment variable:
   docker run --rm -i --network=host \
     -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
     lifx-mcp-server

   # Using argument (least recommended):
   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令牌（优先级顺序）

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

配置：配置文件

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

Example configuration file (~/.lifx-api-mcp-server.jsonc)

{
  // 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令牌， *不要* 在客户端设置中将其作为参数传递。

客户端设置：Claude Desktop

1. 安装 克劳德桌面.

1. 查找或创建 claude_desktop_config.json:

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

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

   {
     "mcpServers": {
       "lix-api": {
         // Use the full path to npx if it's not in your default PATH
         "command": "/path/to/your/npx", // Or node
         "args": [
           // NPX example: (NO TOKEN HERE if set in config/env)
           "-y",
           "lifx-api-mcp-server@latest"

           // Node.js from source example: (NO TOKEN HERE if set in config/env)
           // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
         ],
         "env": {
            // Optional: Uncomment for verbose logging
            // "CONFIG_LOG_LEVEL": "verbose"
            // Optional: Set token via env if not using config file
            // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
         }
       }
     }
   }

1. 重新启动克劳德桌面。

1. 开始聊天并尝试与您的灯进行交互（例如，“@lixapi list my lights”）。

客户端设置：MCP检查器

MCP检查员 对调试很有用。

# 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 具有适当的文件权限）或环境变量比将令牌作为命令行参数传递更安全，特别是在共享环境或日志中。
• 数据流： 使用远程LLM（如通过Claude Desktop）时，您的提示 *向* LLM和 *结果* 此MCP服务器返回的（灯光名称、状态、场景名称）将发送给LLM提供程序。如果隐私是一个主要问题，请注意灯光/组/位置/场景标签中的潜在敏感信息。
• 本地执行： 此服务器在您的计算机上本地运行。它通过HTTPS与LIFX云API直接通信。

教程

确保服务器正在运行并已连接到MCP客户端。替换占位符，如 label:MyLamp 使用您的实际灯光/组/位置标签或ID。

1. 检查可用灯光（资源）：

- @lix-api:lifx://lights - ➥ Uses lights 资源

1. 获取特定的灯光状态（资源）：

- @lix-api:lifx://light/label:Office Lamp/state - ➥ Uses light-state 资源

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

- @lix-api:lifx://scenes - ➥ Uses scenes 资源

1. 使用选择器帮助程序（提示）：

- @lix-api:selector-helper goal: "the lights in the kitchen" - ➥ Uses selector-helper 提示

1. 创建效果（提示）：

- @lix-api:effect-creator effect_type:breathe selector:all description:"a very slow fade to warm white" - ➥ Uses effect-creator 提示（按照指示进行响应）

1. 灯故障排除（提示）：

- @lix-api:troubleshooter selector:"id:d073d5xxxxxx" - ➥ Uses troubleshooter 提示

1. 列出您的灯光（工具）：

- _“列出我的灯”_ 或 _“列表灯选择器：全部”_ - ➥ Uses list-lights 工具

1. 打开灯（工具）：

- _“打开名为办公灯的灯”_ 或 _“设置状态选择器：标签：办公灯电源：打开”_ - ➥ Uses set-state 工具

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

- _“将厨房组灯设置为蓝色，亮度为50%，持续3秒”_ - _“设置状态选择器：组：厨房颜色：蓝色亮度：0.5持续时间：3”_ - ➥ Uses set-state 工具

1. 切换位置（工具）：

- _“打开客厅的灯”_ 或 _“切换电源选择器：位置：客厅”_ - ➥ Uses toggle-power 工具

1. 增加亮度（工具）：

- _“使所有灯亮10%”_ 或 _“状态增量选择器：所有亮度：0.1”_ - ➥ Uses state-delta 工具

1. 激活场景（需要资源/工具中的场景UUID）：

- _“使用uuid abcdef12-3456-激活场景…”_ - _“激活场景sceneuuid:abcdef12-3456-…”_ - ➥ Uses activate-scene 工具

Docker 文件

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股份有限公司）。
• 确保您了解LIFX API速率限制（每个令牌120次请求/分钟），以避免临时阻塞。如果发生以下情况，则记录速率限制信息 logLevel 是 verbose.
• 此服务器部分是在人工智能的帮助下生成的，可能包含错误。

支持

如果您发现此工具有用，请考虑支持开发人员（可选）：

给我买杯咖啡 |