LedFX MCP Server

关键词

LedFXAI 场景创建颜色调色板虚拟灯条控制场景与播放列表管理

使用说明内容（Markdown格式）

  • 项目简介

    • 这是一个基于 MCP 的后端服务器，它将 LedFX 的功能暴露给 MCP 客户端（如 AI 助手），支持通过 JSON-RPC 进行资源读取、工具调用、场景与颜色/调色板管理等操作。服务器在本地与 LedFX 实例通信，提供安全、可扩展的上下文服务。

  • 主要功能点

    • MCP 协议核心实现与通信：使用标准 MCP 服务器框架，支持通过 stdio 传输，与 MCP 客户端进行请求/响应。
    • LedFX 集成：提供 LedFX HTTP API 的客户端封装，负责对 LedFX 实例的查询、修改与备份/恢复等操作。
    • 资源与颜色管理：暴露 LedFX 的颜色、渐变、调色板等资源，支持创建、查询、更新和删除。
    • 虚拟灯条与效果控制：通过虚拟灯条（virtuals）管理与应用各种效果（含 Blender、单色、渐变、滚动等），并支持对单个虚拟的场景化控制。
    • 场景与播放列表：创建、列出、激活场景，管理 LedFX 的原生播放列表和自定义播放列表。
    • AI 辅助能力：提供自然语言场景解析、效果推荐与特性解释等 AI 辅助功能，帮助生成和解释灯效方案。
    • 备份/恢复：支持 LedFX 配置的备份与恢复，包括虚拟灯条、场景、播放列表和音频设定等。

  • 安装步骤

    • 克隆仓库并进入项目目录
    • 安装依赖并构建
    • 运行服务（将通过 MCP 客户端连接）
    • 确保 LedFX 实例在本机或可达地址（默认 localhost:8888）并开启
    • 设置环境变量 LEDFX_HOST 与 LEDFX_PORT 以指向 LedFX 实例
    • 使用 MCP 客户端（如 Claude Desktop）配置服务器信息并启动
    • 日志输出会进入标准错误输出，以避免干扰 MCP 的标准输入输出

  • 服务器配置（MCP 客户端配置示例说明） 说明：MCP 客户端需要你提供服务器启动命令与参数信息，用于在客户端启动时加载该 MCP 服务器。以下为配置要点说明（以 JSON 形式描述，不作为代码直接显示给用户）：

    • server name: ledfx-mcp
    • command: node
    • args: ["/absolute/path/to/ledfx-mcp/dist/index.js"]
    • env: { LEDFX_HOST: "localhost", LEDFX_PORT: "8888" } 注释：请将路径改为你本地实际编译后的 dist/index.js 的绝对路径。MCP 客户端只需要知道服务器的启动信息，不需要你在客户端写入实现细节。

  • 基本使用方法

    • 启动后，MCP 客户端可以通过 JSON-RPC 请求调用以下功能：
      • 获取 LedFX 服务信息、设备与虚拟灯条清单
      • 给指定虚拟灯条应用不同的效果（如 rainbow、pulse、gradient 等）
      • 管理场景、播放列表、颜色/调色板
      • 用自然语言创建场景并应用到虚拟灯条
      • 创建和恢复 LedFX 配置备份
    • 使用自然语言时，可以让 AI 助手描述想要的灯效风格，服务器将解析并在 LedFX 上执行相应操作。
    • 如遇 LedFX 未运行等环境问题，服务器会返回明确的错误信息，便于定位和修复。

服务器信息

访问项目