Flstudio Mcp

flstudio-mcp

用 Claude 控制 FL Studio：通过自然语言进行 AI 混音、编曲和混音诊断。

Claude 通过自然语言在 FL Studio 中诊断并修复混音。

概述

flstudio-mcp 是一个模型上下文协议（MCP）服务，可让 Claude Desktop 直接操控 FL Studio 2025，包括混音器、插件、钢琴卷帘、路由和项目，全部通过普通语言请求完成。你可以要求诊断混音、设置人声效果链、创作特定音阶中的和弦进行，或完成整首编曲；Claude 会通过 FL 的脚本 API 和一系列经过校准且带安全检查的工具来执行。

它不受流派和制作人限制：它不会假设你创作的是某种特定风格的音乐。

快速入门

scripts\install_windows.bat        :: controller + server + note bridge
fl-studio-mcp-daemon               :: start the bridge, keep it running

./scripts/install_macos.sh         # macOS: controller + server + note bridge
fl-studio-mcp-daemon               # start the bridge, keep it running

在 FL 中连接两个虚拟 MIDI 端口（Windows 上使用 loopMIDI，macOS 上使用 IAC Driver），在钢琴卷帘中将 MCP_Apply 启用一次，然后用普通语言向 Claude 提问：

“扫描我的混音，告诉我有什么问题。”——“用我的插件设置一条人声效果链。”——“将这首编曲导出为 MIDI。”

完整设置步骤如下。

功能

混音与诊断

• 混音医生——扫描整首混音并报告具体问题（削波、余量不足、电平不平衡、缺少高通滤波器、相关音轨未分组、EQ 增益重叠），并为每个问题提供确切依据和建议的修复方法。修复会一次应用一项，且仅在获得批准后通过“快照 → 写入 → 回读 → 回滚”安全层执行。解决主输出削波时，会降低造成问题的源音轨电平，而不是拉低主输出。
• 全曲峰值监测——在播放期间持续记录每条音轨的峰值，因此电平调整依据的是整首歌曲中实际出现的最高电平，而非某个瞬间的电平。
• 经过校准的处理意图——将音乐性 EQ、压缩、混响和延迟调整映射到实际插件参数（原生和第三方插件均适用），每项调整都可以单独撤销。
• 电平感知压缩——根据音轨播放期间测得的电平设置阈值。
• 增益分级——为每条音轨建议合适的电平调整，使电平达到健康范围，同时为主输出留出适当余量。
• 参考匹配——将混音的电平和音调平衡与参考曲目进行比较。
• 批量音轨控制——一步即可独奏或静音一整组音轨（鼓、人声等），并可通过一次调用重置。
• 音轨与通道着色——按颜色名称或十六进制值为单条音轨、单个通道或整组音轨（鼓、人声等）着色，且与其他更改一样可以撤销。

插件与预设控制

• 按名称读取和设置原生及第三方插件的参数（参数列表会实时解析）。
• 效果链建议和预设推荐根据你实际安装的库生成——直接从 FL 的插件数据库和磁盘上的预设文件夹读取，因此推荐内容仅限于你拥有的资源。

作曲

• 多轨 MIDI 导出——生成完整编曲，并导出为可供导入的标准 MIDI 文件。
• 多乐段编曲——创建、命名、克隆并标记乐段。
• 钢琴卷帘中的音符与和弦写入，并可量化到网格（适用于新音符和现有音符）。
• 任意音阶或调式作曲——通过音阶作曲器创作，涵盖西方调式、五声音阶、拉格、maqam 等；Claude 会根据请求的音阶提供音符。

音频分析

• 从音频文件估算速度和调性。
• 将旋律转录为 MIDI（使用 CREPE 音高跟踪，并提供更轻量的备用方案）。

该服务提供 14 个类别的 67 种工具，以及 6 个实时资源（项目、混音器、传输、通道、模式、状态），Claude 可直接读取这些资源。

与众不同之处

flstudio-mcp 是一款混音和制作助手，而不只是音符发送器。它能诊断并修复整个混音，根据实际测得的电平而非猜测做出判断，并会在提出建议时考虑你实际拥有的插件和预设库。所有会影响项目的更改都会在应用前显示出来、记录在日志中，并且可以撤销。

限制

以下是 FL Studio 脚本 API 的限制，如实说明：

• 插件、音频文件和渲染只能通过 UI 操作。 FL 的 API 无法加载插件、加载音频文件或渲染音频。因此，插件和预设工具只会给出建议——你需要加载选定的插件或预设，然后 Claude 会进行配置。音频导出需手动完成（File > Export）；之后 Claude 可以分析渲染出的文件。
• 每次会话只需启用一次音符写入。 生成的 pyscript 会将音符写入钢琴卷帘；FL 不提供运行 pyscript 的 API，因此你需要在会话开始时，从钢琴卷帘的脚本菜单运行一次“MCP_Apply”。
• 微分音和大量使用 gamaka 的音乐只能近似处理。 间隔小于半音的音阶（如阿拉伯 maqam）会四舍五入到最接近的半音；以 gamaka/装饰音为基础的传统音乐（如 Carnatic）只能获得音阶框架——正确的 swara 和音程，而无法还原 gamaka 或微分音。这是 12 音 MIDI 的限制，而非这些工具的限制。

要求

• Windows 10/11（已在 Windows 11 上测试）或 macOS
• FL Studio 2025 或更新版本
• Claude Desktop（或任意 MCP 客户端）
• Python 3.10+
• 虚拟 MIDI 端口：
  • Windows：loopMIDI（下载）
  • macOS：内置的 IAC Driver
• 可选：将 ffmpeg 加入 PATH（用于 MP3 分析）

目前尚不支持 Linux，欢迎贡献。

设置

1. 创建两个虚拟 MIDI 端口，名称必须严格为 FLStudioMCP RX 和 FLStudioMCP TX。

   Windows：在 loopMIDI 中创建这两个端口。

   macOS：

   • 打开 音频 MIDI 设置。
   • 选择 窗口 > 显示 MIDI 工作室。
   • 双击 IAC Driver。
   • 启用 设备已连接。
   • 创建或重命名两个端口，名称必须严格为：
     • FLStudioMCP RX
     • FLStudioMCP TX

2. 安装控制器脚本和服务：

   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]"
   

3. 配置 FL Studio — 选项 > MIDI 设置：

   • 启用 FLStudioMCP RX 作为输入，将其控制器类型设为 FLStudioMCP，并为其指定端口号。
   • 启用 FLStudioMCP TX 作为输出，并使用相同的端口号。
   • 查看 > 脚本输出中应显示 [FLStudioMCP] Ready。

4. 启动桥接守护进程（推荐），让 MIDI 端口由稳定的进程占用：

   fl-studio-mcp-daemon
   

5. 将服务注册到 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 端口。

6. 启用音符桥接（每个会话都需操作） — 打开钢琴卷帘，在脚本菜单中运行一次 MCP_Apply，即可写入音符。

   在 macOS 上，音符桥接会通过 Cmd+Opt+Y 重新触发已启用的脚本。 请向运行 MCP 服务或守护进程的应用授予辅助功能权限，例如 Terminal、iTerm、Claude Desktop 或 Cursor： 系统设置 > 隐私与安全性 > 辅助功能。

让 Claude 调用 fl_ping，验证连接是否正常。

故障排除

症状	解决方法
未找到／未检测到虚拟 MIDI 端口	两个端口的名称必须严格为 FLStudioMCP RX 和 FLStudioMCP TX。在 loopMIDI（Windows）或 IAC Driver（macOS）中重新创建端口，然后重新运行安装程序。
FL 的脚本输出中没有 [FLStudioMCP] Ready	控制器未注册：在 MIDI 设置中，将 FLStudioMCP RX 输入的控制器类型设为 FLStudioMCP；确认 device_FLStudioMCP.py 位于 Settings\Hardware\FLStudioMCP\ 中，然后彻底重启 FL Studio。
Claude 无法连接到 FL／fl_ping 失败	确认守护进程正在运行（fl-studio-mcp-daemon）；检查传输方式是否匹配（FLSTUDIO_MCP_TRANSPORT=tcp 表示使用守护进程，未设置则使用直接 MIDI）；编辑配置后重启 Claude Desktop。
写入音符没有效果	在本次会话中，从钢琴卷帘的脚本菜单运行一次 MCP_Apply，以启用音符桥接。
macOS 音符触发失败	向运行 MCP 服务或守护进程的应用授予辅助功能权限，然后点击 FL 钢琴卷帘并尝试 Cmd+Opt+Y。
音频工具报错或不可用	安装可选扩展：pip install -e ".[audio]"（或 ".[audio,audio-accurate]"）。

使用示例

自然语言提示词：

• “扫描我的混音并告诉我哪里有问题。”
• “用我的插件为主唱设置一条人声效果链。”
• “从我的 Serum 音色库中推荐一个复古贝斯预设。”
• “用 D Dorian 创作一段 8 小节旋律，并将其写入所选通道。”
• “将这个编曲导出为 MIDI 文件。”
• “这首曲子的速度和调性是什么？”（用于音频文件）

架构

一个精简的控制器脚本在 FL Studio 内运行，只返回开销低的原始数据；所有判断——诊断、校准、规划——都在服务端完成。一个独立的守护进程负责管理 MIDI 端口，因此无论如何启动 MCP 客户端，服务都能正常运行。音符编写通过生成的 pyscript 桥接实现：守护进程先短暂地将窗口设为焦点，再通过平台的“运行上一个脚本”快捷键重新触发已准备好的 MCP_Apply 脚本。每个会修改项目的工具都会经过快照 → 写入 → 回读 → 回滚安全层，该安全层由持久化变更日志提供支持。

设计说明和研究结果见 docs/。

许可证

MIT——详见 LICENSE。

状态与贡献

测试版——公开发布的 1.0 版本。支持 Windows 和 macOS；欢迎为 Linux 贡献。问题和拉取请求：github.com/rosasynthesiz/flstudio-mcp。