flstudio-mcp 是一个 Model Context Protocol（MCP）服务器，用于通过自然语言控制 FL Studio 2025。它由 Claude Desktop 或其他 MCP 客户端驱动，可操作 FL 的混音器、插件、钢琴卷帘窗、路由和项目文件。该项目定位为混音与制作助手，而非单纯的音符发送工具。
用途
- 通过自然语言向 Claude 发出请求，例如“扫描我的混音并告诉我哪里有问题”“用我的插件搭建一条人声链”“在 D 多利亚调式下创作 8 小节旋律并写入选中通道”“把这个编排导出为 MIDI 文件”。
- 覆盖混音诊断、插件与预设控制、编曲与作曲等环节。
主要能力
混音与诊断
- Mix Doctor：扫描整个混音并报告具体问题（削波、余量不足、电平失衡、缺少高通、相关轨道未编组、EQ 提升重叠等），每项问题附带证据和修复建议。修复逐条应用，且仅在批准后执行，经过快照 → 写入 → 回读 → 回滚的安全层。主输出削波通过削减相关源轨道解决，而不是拉低主输出。
- 全曲峰值监视：在播放过程中持续记录每条轨道的峰值，使电平决策基于实际歌曲的最响时刻。
- 校准处理意图：将音乐性的 EQ、压缩、混响和延迟操作映射到真实插件参数（原生与第三方），每次只应用一个可逆改动。
- 电平感知压缩：根据播放期间测得的轨道电平设置阈值。
- 增益分级：建议逐轨削减，朝向健康电平并为主输出保留适当余量。
- 参考匹配：将混音的电平和音色平衡与参考轨道比较。
- 批量轨道控制：一步独奏或静音整组轨道（鼓、人声等），并提供一次调用重置。
- 轨道与通道着色：按颜色名称或十六进制值为轨道、通道或整组着色，可逆。
插件与预设控制
- 按名称读取和设置插件参数，支持原生和第三方插件（参数列表实时解析）。
- 基于实际已安装库提供链路建议和预设推荐：直接读取 FL 的插件数据库和磁盘上的预设文件夹，因此推荐限于用户已有的内容。
- 多轨 MIDI 导出：将完整编排生成为标准 MIDI 文件以供导入。
- 多模式编排：创建、命名、克隆和标记段落。
- 向钢琴卷帘窗写入音符与和弦，支持量化到网格（新建和已有音符均可）。
- 通过音阶作曲家支持任意音阶或调式（西方调式、五声音阶、raga、maqam 等），由 Claude 提供所需音阶的音符。
- 从音频文件估计速度和调性。
- 旋律转 MIDI（CREPE 音高追踪，并带有较轻量的回退方案）。
工具规模
- 服务器暴露 67 个工具，分为 14 个类别，另有 6 个实时资源（项目、混音器、传输、通道、模式、状态）可供 Claude 直接读取。
使用方式
前置条件
- Windows 10/11（已在 Windows 11 测试）或 macOS。
- FL Studio 2025 或更新版本。
- Claude Desktop（或任意 MCP 客户端）。
- 虚拟 MIDI 端口：Windows 使用 loopMIDI，macOS 使用内置 IAC Driver。
- 可选：PATH 中的 ffmpeg（用于 MP3 分析）。
- Linux 暂不支持。
创建虚拟 MIDI 端口
- 创建两个虚拟 MIDI 端口，名称必须精确为 FLStudioMCP RX 和 FLStudioMCP TX。
- Windows：在 loopMIDI 中创建两个端口。
- macOS：打开音频 MIDI 设置，选择“窗口 > 显示 MIDI 工作室”，双击 IAC Driver，启用“设备在线”，创建或重命名两个端口为上述精确名称。
安装控制器脚本和服务器
- Windows： git clone https://github.com/rosasynthesiz/flstudio-mcp cd flstudio-mcp scripts\install_windows.bat
- macOS： git clone https://github.com/rosasynthesiz/flstudio-mcp cd flstudio-mcp chmod +x scripts/install_macos.sh ./scripts/install_macos.sh
- 安装过程会复制控制器脚本、植入音符桥接 pyscript（MCP_Apply）、安装服务器并检查虚拟 MIDI 端口是否存在。
- 音频功能需要可选附加组件： pip install -e ".[audio]" pip install -e ".[audio,audio-accurate]"
配置 FL Studio
- 打开“选项 > MIDI 设置”。
- 将 FLStudioMCP RX 启用为输入，控制器类型设为 FLStudioMCP，并分配端口号。
- 将 FLStudioMCP TX 启用为输出，使用相同端口号。
- “视图 > 脚本输出”应显示 [FLStudioMCP] Ready。
启动桥接守护进程（推荐）
- 运行 fl-studio-mcp-daemon，让 MIDI 端口由稳定进程持有。
在 Claude Desktop 中注册服务器
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- 配置内容： { "mcpServers": { "fl-studio": { "command": "fl-studio-mcp", "env": { "FLSTUDIO_MCP_TRANSPORT": "tcp" } } } }
- tcp 会经由守护进程路由，无论 Claude Desktop 如何启动服务器均可工作。省略该环境变量则让服务器直接打开 MIDI 端口。
每次会话启用音符桥
- 打开钢琴卷帘窗，在其脚本菜单中运行一次 MCP_Apply，使音符写入可用。
- macOS 上，音符桥通过 Cmd+Opt+Y 重新触发已启用脚本。需要为运行 MCP 服务器或守护进程的应用授予辅助功能权限（系统设置 > 隐私与安全性 > 辅助功能）。
验证连接
- 让 Claude 调用 fl_ping 进行验证。
示例提示语
- “扫描我的混音并告诉我哪里有问题。”
- “用我的插件为主唱人声搭建一条人声链。”
- “从我的 Serum 库中推荐一个复古贝斯预设。”
- “在 D 多利亚调式下创作 8 小节旋律并写入选中通道。”
- “把这个编排导出为 MIDI 文件。”
- “这首曲子的速度和调性是什么？”（针对音频文件）
适用场景
- 需要快速诊断和修复混音问题的制作人。
- 希望通过自然语言完成编曲、和弦与旋律写作的用户。
- 想基于自己已安装的插件和预设库获得建议的制作人。
- 需要在 FL Studio 中执行多轨 MIDI 导出、音阶作曲、速度/调性估计等任务。
限制
- 插件、音频文件和渲染仅限 UI 操作：FL 的脚本 API 无法加载插件、加载音频文件或渲染音频。因此插件和预设工具只能给出建议，由用户自行加载，然后 Claude 再进行配置。音频导出需手动完成（文件 > 导出），之后 Claude 可以分析导出的文件。
- 音符写入需要每次会话启用一次：生成的 pyscript 将音符写入钢琴卷帘窗，但 FL 未提供运行 pyscript 的 API，因此需在会话开始时从钢琴卷帘窗的脚本菜单运行一次 MCP_Apply。
- 微分音和装饰音密集的音乐只能近似处理：音程小于半音的音阶（如阿拉伯 maqam）会四舍五入到最近的半音；以 gamaka/装饰音为基础的传统（如 Carnatic）只提供音阶框架（正确的 swaras 和音程），不提供 gamaka 或微分音渲染。这是 12 音 MIDI 的限制，而非工具本身的限制。
- Linux 暂不支持。
架构说明
- 一个轻量控制器脚本在 FL Studio 内运行，只返回廉价原始数据；所有判断（诊断、校准、规划）在服务器端完成。
- 独立守护进程持有 MIDI 端口，使服务器在 MCP 客户端以任何方式启动时都能工作。
- 音符创作使用生成的 pyscript 桥：守护进程在短暂强制聚焦窗口后，使用平台的“运行上次脚本”快捷键重新触发已启用的 MCP_Apply 脚本。
- 所有修改项目的工具都经过快照 → 写入 → 回读 → 回滚的安全层，并带有持久化变更日志。
- 设计说明和发现记录位于 docs/ 目录。
许可与状态
- MIT 许可，详见 LICENSE。
- 状态为 Beta，公开 1.0 发布。支持 Windows 和 macOS，欢迎 Linux 贡献。问题与拉取请求请访问 github.com/rosasynthesiz/flstudio-mcp。
