JinDaGe - ledfx-mcp MCP Details

article

README

🚀 LedFX MCP 服务器

LedFX MCP 服务器是一个模型上下文协议（MCP）服务器，它使 AI 助手能够与本地 LedFX 实例进行交互并对其进行控制。该服务器为 AI 助手（如 Claude）和 LedFX 之间搭建了桥梁，让你可以通过自然语言控制 LED 照明设置。

🚀 快速开始

LedFX MCP 服务器可帮助你通过 AI 助手以自然语言的方式控制 LED 照明。要使用该服务器，你需要满足以下先决条件：

Node.js 24 或 25
一个正在运行的 LedFX 实例（默认：localhost:8888）
一个与 MCP 兼容的 AI 助手（例如，Claude Desktop）

运行 LedFX 进行测试

使用 Docker（推荐）

# 使用 docker-compose（包含在本仓库中）
docker-compose up -d

# 或者使用 docker run
docker run -d --name ledfx -p 8888:8888 ledfxorg/ledfx:latest

使用 pip

pip install ledfx
ledfx --host 0.0.0.0 --port 8888

安装

# 克隆仓库
git clone https://github.com/abossard/ledfx-mcp.git
cd ledfx-mcp

# 安装依赖
npm install

# 一键构建并运行
npm run dev

配置

服务器使用以下环境变量连接到 LedFX：

LEDFX_HOST：LedFX 服务器主机（默认：localhost）
LEDFX_PORT：LedFX 服务器端口（默认：8888）

你可以在 MCP 客户端配置中设置这些变量，也可以将其作为环境变量设置。

Claude Desktop 配置

将以下内容添加到你的 Claude Desktop 配置文件中：

Claude Desktop 通过标准输入输出启动此 MCP 服务器。
使用 Node.js 24 或 25。
使用 node 运行 dist/index.js 时，路径必须为绝对路径。

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ledfx": {
      "command": "node",
      "args": ["/absolute/path/to/ledfx-mcp/dist/index.js"],
      "env": {
        "LEDFX_HOST": "localhost",
        "LEDFX_PORT": "8888"
      }
    }
  }
}

如果你想直接从 Git 运行而不进行本地构建，可以使用 npx 作为命令：

{
  "mcpServers": {
    "ledfx": {
      "command": "npx",
      "args": ["github:abossard/ledfx-mcp"],
      "env": {
        "LEDFX_HOST": "localhost",
        "LEDFX_PORT": "8888"
      }
    }
  }
}

✨ 主要特性

🎨 通过自然语言控制 LED 效果
🔧 管理多个 LED 设备和虚拟设备
🎭 激活预配置场景
📊 查询设备和系统信息
🔒 采用类型安全的 TypeScript 实现
🏗️ 遵循软件设计最佳实践构建
🎨 通过 /api/colors 提供 LedFX 颜色和渐变（内置 + 用户自定义）
🗂️ 调色板管理，以用户渐变的形式存储在 LedFX 中
🤖 基于自然语言描述实现 AI 场景创建
📝 支持 播放列表，用于场景序列
💡 基于情绪和描述提供 效果推荐
📚 提供 LedFX 功能解释，帮助你了解任何 LedFX 概念
🔄 正确的 API 实现，使用虚拟设备（而非物理设备）应用效果

📦 安装指南

# 克隆仓库
git clone https://github.com/abossard/ledfx-mcp.git
cd ledfx-mcp

# 安装依赖
npm install

# 一键构建并运行
npm run dev

💻 使用示例

基础用法

配置完成后，你可以通过自然语言与 LedFX 设置进行交互：

基本操作：
- "列出我所有的 LED 虚拟设备"
- "在我的桌面灯虚拟设备上激活彩虹效果"
- "显示所有可用场景"
- "清除所有虚拟设备上的效果"
自然语言场景创建：
- "创建一个带有缓慢蓝色波浪的平静海洋场景"
- "创建一个带有快速彩虹颜色的活力派对场景"
- "创建一个带有淡粉色和紫色渐变的浪漫场景"
- "创建一个带有中等亮度稳定白光的专注场景"
颜色和调色板管理：
- "列出所有 LedFX 颜色和渐变"
- "获取颜色或渐变 '日落'"
- "创建用户颜色 '我的洋红色' = #FF00FF"
- "创建一个名为 '日落氛围' 的新调色板，包含 #FFA500、#FF69B4、#800080"
- "保存我的派对场景播放列表"
效果推荐：
- "推荐适合放松夜晚的效果"
- "哪些效果与音乐搭配效果好？"
- "为派对推荐一些活力四射的效果"
学习 LedFX：
- "解释 LedFX 中的虚拟设备是什么"
- "设备和虚拟设备有什么区别？"
- "音频响应效果是如何工作的？"
- "告诉我关于 WLED 设备的信息"
- "列出所有可用的效果类型"

📚 详细文档

API 规范

docs/API_SPECIFICATION.md

LedFX REST API 端点的完整参考（已针对 LedFX 2.1.4 和上游源代码进行验证）：

所有端点路径、方法和参数
数据模型和编排注意事项（虚拟设备、预设、场景、播放列表、混合器）
API 行为怪癖和兼容性说明

测试规范

docs/TEST_SPECIFICATION.md

全面的测试要求和测试用例：

所有组件的单元测试用例
集成测试场景
端到端工作流程
性能测试标准
兼容性测试矩阵
模拟策略和测试夹具
基于 Docker 的测试环境设置

实现说明

docs/IMPLEMENTATION_NOTES.md

对当前实现与实际 API 的关键分析：

已知问题和漏洞（设备与虚拟设备混淆）
生产使用前需要修复的问题
缺失的功能和功能差距
推荐的实现阶段
未来版本的迁移路径

参考资料

docs/REFERENCES.md

用于 API 验证的简洁源索引：

官方 LedFX 文档链接
版本发布链接
用于验证 API 行为的上游源文件

🔧 技术细节

设计原则

本项目遵循以下原则：

Grokking Simplicity

关注点分离：操作（I/O 操作）与计算（纯函数）明确分离
分层设计：有清晰的抽象层（工具 → 客户端 → API）
不可变性：数据转换尽可能使用纯函数

A Philosophy of Software Design

深度模块：复杂的 LedFX API 交互隐藏在简单的接口后面
信息隐藏：实现细节对调用者进行抽象
最小化复杂性：每个模块都有单一、专注的职责

实现状态

当前状态：已实现并具备全面的测试套件

此 MCP 服务器是针对当前 LedFX API 实现的，并通过自动化测试和持续集成检查进行了验证。该实现修复了关键的 API 问题（虚拟设备与物理设备），并添加了高级功能，如调色板管理、自然语言场景创建和 AI 推荐。

重要说明

应用了 API 修正：效果正确应用于虚拟设备（而非物理设备），符合当前 LedFX API 行为
全面测试：34 个测试涵盖单元和端到端场景，全部通过
CI/CD 管道：GitHub Actions 工作流，包含 lint、构建、测试和覆盖率任务
生产就绪：有完整的文档，包括安装指南、使用示例和架构文档

架构

服务器分为三个主要层：

MCP 服务器层 (index.ts)：处理 MCP 协议通信
工具层 (tools.ts)：定义可用工具并路由请求
客户端层 (ledfx-client.ts)：抽象 LedFX HTTP API 交互

这种分层架构确保了：

清晰的关注点分离
易于测试和维护
便于扩展新功能

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

资源

故障排除

服务器无法连接到 LedFX

确保 LedFX 正在运行，并且可以通过配置的主机/端口访问
检查防火墙设置
验证 LEDFX_HOST 和 LEDFX_PORT 环境变量

工具未在 Claude 中显示

配置更改后重启 Claude Desktop
验证 dist/index.js 的路径是否为绝对路径
检查 Claude Desktop 日志以查找错误

支持

如有问题或疑问，请通过以下方式寻求帮助：

ledfx-mcp