FL Studio MCP

用自然语言操作 FL Studio，并把参考音频转换成可编辑工程，或在现有插件中搜索接近的音色。

下载 Windows EXE · 参数示例 · 报告问题

FL Studio MCP 是运行在本机的 Model Context Protocol（MCP）服务器。支持 MCP 的 AI 客户端负责理解你的话，再通过本项目读取工程、写鼓点、控制插件、录制试听并分析结果。它本身不需要模型 API Key，也不内置大语言模型。

当前版本 0.6.0 提供 31 个工具。完整还原任务使用独立后台进程，工具连接关闭后仍可继续运行；重连后可查询进度和结果。

当前“整曲还原”的含义：根据参考音频，近似重建 4/4 拍音乐的鼓、三和弦、低音和段落，再通过你准备的乐器模板生成 FLP、MIDI 和 WAV。当前不包含人声分离、独立主旋律转录、逐轨音色自动匹配或一比一成品复刻。

目录

• 1. 能做什么

• 2. 环境与兼容性

• 3. 安装与首次连接

• 4. 完整音乐还原

• 5. 单音色还原

• 6. 日常编曲与试听

• 7. 工具与参数参考

• 8. 数据、任务与恢复

• 9. 工作原理

• 10. 常见问题

• 11. 开发、测试与打包

• 12. 验证结果与能力边界

• 13. 许可证与参考资料

Related MCP server: FL Studio MCP Server

1. 能做什么

例如，你可以对已连接的 AI 说：

读取当前 FL 工程，告诉我有哪些乐器。
用 E:\Music\reference.wav 做整曲还原，输出到 E:\FL-MCP\recreations。
用当前 FLEX Bass 通道匹配 E:\Music\bass-note.wav，先搜索滤波参数。
听一下这个 lead 是否太闷，给我测量结果和调整建议。
把速度改成 92 BPM，写一个 4 小节的 lo-fi 鼓型。

这些句子由 AI 客户端解释；下文 JSON 是对应 MCP 工具的参数对象，不是直接粘贴到 FL 中执行的代码。

2. 环境与兼容性

实时录音优先使用 WASAPI 进程回环，捕获 FL64.exe 及其子进程的输出。Microsoft 的参考实现要求 Windows build 20348 或更高，因此这里不承诺所有 Windows 10 版本都支持该路径。Microsoft 文档

源码安装可选 system-loopback 依赖，在进程录音不可用时尝试系统回环。系统回环会同时录入其他应用声音，此时应关闭其他音源；它不是只录 FL 的等价替代方案。当前发布 EXE 不将此可选依赖作为必备能力。

3. 安装与首次连接

3.1 使用 EXE

1. 从 Releases 下载 Windows ZIP，解压到固定目录，例如 E:\Tools\fl-studio-mcp。其中包含 fl-studio-mcp.exe、说明和许可证。

2. 安装 loopMIDI。保存并关闭 FL Studio。

3. 在 PowerShell 中运行：

Set-Location E:\Tools\fl-studio-mcp
.\fl-studio-mcp.exe --version
.\fl-studio-mcp.exe setup

setup 会检查依赖、配置 loopMIDI 端口、安装 FL 脚本、设置 MIDI 路由，并询问是否向检测到的 MCP 客户端添加启动配置。更新客户端配置时会保存备份。

4. 打开 FL，重新连接或重启 AI 客户端，然后运行诊断：

.\fl-studio-mcp.exe doctor
# 也可以输出 JSON，便于排查版本和连接问题
.\fl-studio-mcp.exe doctor --json

正常状态应显示服务器版本 0.6.0、桥接版本 7、connection.state = connected。FL 未打开时，离线分析仍可用，但实时诊断会报告未连接。

其他安装选项：

# 预览配置动作
.\fl-studio-mcp.exe setup --dry-run
# 只配置桥接，不写 AI 客户端配置
.\fl-studio-mcp.exe setup --clients none
# 安装脚本，但跳过 FL MIDI 设置，之后自行配置
.\fl-studio-mcp.exe setup --skip-fl
# 只更新 FL 侧脚本；安装后需要重载脚本或重启 FL
.\fl-studio-mcp.exe install

setup 会跳过已经登记的客户端条目。升级时必须检查客户端的 command 是否指向新 EXE；只下载新文件或再次运行 setup，不一定替换旧启动路径。服务器路径可通过 fl_get_status 核对。

3.2 从源码安装

以下命令在 PowerShell 中执行；路径可改成自己的工作区：

git clone https://github.com/Funkierry/fl-studio-mcp.git E:\Projects\fl-studio-mcp
Set-Location E:\Projects\fl-studio-mcp
python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install .
& .\.venv\Scripts\fl-studio-mcp.exe setup

开发时用 pip install -e . 安装可编辑版本。可选系统回环：

& .\.venv\Scripts\python.exe -m pip install '.[system-loopback]'

源码仓库也提供 python fl-studio-mcp.py 入口；运行时使用的 Python 环境必须已安装依赖。

3.3 手动配置 MCP 客户端

通用 stdio 示例见 examples/mcp-stdio.json：

{
  "mcpServers": {
    "fl-studio": {
      "command": "E:/Tools/fl-studio-mcp/fl-studio-mcp.exe",
      "args": [],
      "env": {
        "FLSTUDIO_MCP_DATA": "E:/FL-MCP/data",
        "TEMP": "E:/FL-MCP/temp",
        "TMP": "E:/FL-MCP/temp"
      }
    }
  }
}

先创建所用目录。FLSTUDIO_MCP_DATA 保存任务状态、分析、录音及模板快照；TEMP/TMP 控制临时目录。AI 客户端启动的进程不一定继承你某个 PowerShell 窗口的环境变量，需要在客户端配置中填写这些值。

Codex 的 TOML 配置可写成：

[mcp_servers.fl-studio]
command = "E:/Tools/fl-studio-mcp/fl-studio-mcp.exe"

[mcp_servers.fl-studio.env]
FLSTUDIO_MCP_DATA = "E:/FL-MCP/data"
TEMP = "E:/FL-MCP/temp"
TMP = "E:/FL-MCP/temp"

以上是片段，请合并进现有配置，不要覆盖其他服务器。VS Code 的 MCP JSON 使用 servers 顶层键和 type: "stdio"；其他客户端按自己的格式填写同一命令。

3.4 手动配置 FL 的 MIDI 路由

在 FL 中按 F10 → MIDI，配置如下：

输出列表中只能有 FL Agent Reply 使用端口 10。 两个输出都设为 10，可能把回复送回请求端口，表现为超时或脚本似乎没有响应。输入与输出中的 FL Agent 是不同设置，不要把输入端也关掉。

默认脚本安装位置位于 FL 用户数据目录：

Settings/Hardware/FL Studio MCP/device_FLStudioMCP.py
Settings/Piano roll scripts/MCP - Apply notes.pyscript

若 FL 使用自定义用户数据目录，在安装脚本和启动 MCP 时都设置 FLSTUDIO_USER_DIR，指向 FL 的“用户数据文件夹”，不是 FL 程序安装目录。

4. 完整音乐还原

4.1 准备一次乐器模板

模板决定还原工程使用哪些鼓采样、合成器、预设和混音设置。工具不会根据整首混音自动选择并加载全部乐器。

在 FL Studio 24 新建一个专用模板：

1. 准备 Kick、Snare、Hat、和弦、Bass 五个不同通道。

2. 建立五个 Pattern，名称分别为 Full Kick、Full Snare、Full Hat、Full Chords、Full Bass。

3. 每个 Pattern 只在对应通道中至少放一个钢琴卷帘音符，用于识别通道映射。不要只保留没有音符的空 Pattern。

4. 将五个 Pattern 作为未经裁切的片段放入同一 Arrangement 播放列表。

5. 鼓采样按默认 MIDI 60 根音设置；不要在模板中放 Pattern 自动化。

6. 保存为 instrument-template.flp。

建议模板只保留需要的乐器和素材。生成器会保留插件状态、采样引用和混音配置，替换音符、播放列表片段及段落标记；未映射的 Pattern 音符会在新工程中清空。原模板不会被改写。

模板里的外部采样和插件仍需要在本机可用。FLP 不是包含所有音源的自足安装包，仓库与发布包不附带商业预设或采样。

4.2 注册模板与输出目录

调用工具 fl_recreation_config：

{
  "template_path": "E:/Music/instrument-template.flp",
  "fl_executable": "C:/Program Files/Image-Line/FL Studio 2024/FL64.exe",
  "output_root": "E:/FL-MCP/recreations"
}

程序会验证模板、复制快照并保存 SHA-256。之后修改原模板不会悄悄改变已有配置，需要重新注册。无参数调用该工具可查看当前配置。

如果 Pattern 名称不同，注册时同时传入 role_patterns。这里的值是 Pattern 编号，不是通道编号：

{
  "template_path": "E:/Music/instrument-template.flp",
  "role_patterns": {"kick": 1, "snare": 2, "hat": 3, "chords": 4, "bass": 5}
}

4.3 提交整曲任务

保存并关闭正在运行的 FL，然后调用 fl_recreate_music：

{
  "path": "E:/Music/reference.wav",
  "kind": "song",
  "render": true
}

调用立即返回任务编号，例如 recreate-0123456789abcdef，而不是等待整个分析与导出结束。若已知速度，可增加 "tempo_hint": 120；可用 start、end 指定原文件中的起止秒数。

工具会依次完成：读取参考 → 分析节拍/段落/和声 → 编写新 FLP 与 MIDI → 调用 FL 原生渲染 → 检查 WAV → 生成 A/B。

4.4 查询、继续和取消

对 fl_recreation_status 传入：

{"task_id": "recreate-0123456789abcdef"}

若 FL 尚未关闭，会返回 waiting_fl_close。保存并关闭 FL 后继续：

{"task_id": "recreate-0123456789abcdef", "resume": true}

仅 waiting_fl_close 可以通过 resume 继续。它会沿用已生成的工程，不重复创建音符。工具不会自行关闭你原来打开的 FL 窗口。

取消时使用 "cancel": true，已生成文件保留。只有 status: "done" 才表示本次要求的流程完成；进程启动成功或返回码为零都不等于渲染成功。

如果只想得到工程和 MIDI，可在提交时设置 "render": false，这时不需要关闭 FL，也不会生成 WAV 或 A/B。

4.5 输出文件

每次任务创建单独目录：

E:/FL-MCP/recreations/recreate-<id>/
├── reference.wav                           # 本次实际分析的参考片段
├── analysis.json                           # 音频分析结果
├── arrangement.json                        # 声部、音符数量及编曲信息
├── arrangement.mid                         # 可编辑 MIDI
├── recreated.flp                           # 带模板乐器和播放列表的新工程
├── recreated.wav                           # FL 原生导出音频
├── comparison-reference-then-recreated.wav  # 参考 → 0.75 秒静音 → 还原片段
├── verification.json                       # 完整性、响度与频段差异报告
└── render.log                              # 原生渲染进程输出，可能为空

A/B 通常选取副歌或首段，双方各最多 16 秒，以 RMS 衰减方式匹配音量。它是片段对比，不是完整歌曲交替播放；完整结果在 recreated.wav。

工具核验时长、数值有效性、非静音、分段能量与削波。削波和近静音段落会返回警告。报告反映输出是否完整可用，不是音符正确率或人耳相似度评分。

5. 单音色还原

5.1 准备参考与插件

选择尽量干净的单音参考，减少鼓声、其他乐器及背景噪声。可以用 start/end 从文件中截取；这不等于从混音中分离出某个乐器。

在 FL 中选择能产生相近声音的插件和起始预设，停止播放。先调用：

1. fl_get_project：取得实际通道编号。

2. fl_list_params：查看该插件暴露的参数。

例如 fl_list_params 参数：

{"channel": 4, "query": "filter", "limit": 40}

channel: 4 和 params: [10] 只是曾用于 FLEX 测试的示例，不是所有工程/插件的固定编号。 通道从 0 开始，必须按工具返回值填写。

5.2 提交音色搜索

调用 fl_recreate_music，FL 与 MIDI 桥接保持打开：

{
  "path": "E:/Music/bass-note.wav",
  "kind": "sound",
  "channel": 4,
  "params": [10],
  "budget": 20,
  "pitch": 33,
  "note_len_s": 0.7
}

budget 是试音评估次数，范围 2–200。params 限定参与搜索的旋钮；省略时会按参数名称挑选与音色相关的候选。pitch 和按键时长也可省略，由参考声音估计。

后台任务反复播放单音、录音、提取频谱/包络特征、调整参数，并保留测得距离最小的候选。期间不要播放工程、手动弹奏或并行发起其他控制/试听任务，否则会干扰测量。

通过 fl_recreation_status 查询，完成后得到：

若要恢复，把结果中的 revert 数组原样作为 fl_set_params 的 changes，并传入相同通道。例如：

{"channel": 4, "changes": [{"param": 10, "value": 0.4378509521484375}]}

这里的数值只是示例，应使用自己的任务结果。取消搜索也会保留已找到的最佳参数；正常报错时底层匹配器会尝试恢复原参数并报告恢复情况。进程被外部强制终止不能保证执行清理。

“距离下降 7%”指特征距离的相对改善，不代表达到 93% 相似度，也不代表人耳认为改善了 7%。是否可用应试听参考、原始和最佳结果。

6. 日常编曲与试听

鼓、音符和单位

• fl_write_drums 直接写当前 Pattern 的步进鼓；每个字符代表一个十六分音符：x 普通、X 重音、o 轻音、. 休止，空格和 | 可用于分组。

• fl_write_notes 暂存钢琴卷帘音符并打开目标通道。还需要在钢琴卷帘菜单 工具 → 脚本 → MCP - Apply notes 中执行一次。

• 音符 start/length 使用四分音符拍数；4/4 拍一小节为 4 拍。

• 音高使用 MIDI 数字或音名，工具采用 C4 = 60；FL 默认界面把同一 MIDI 音标为 C5，不要因此重复移调。

• 插件参数归一化为 0–1；力度通常使用 0–1，也接受 MIDI 0–127。

脚本重复执行有去重保护。部分 FL 环境中，钢琴卷帘与 MIDI 脚本位于不同解释器，fl_read_piano_roll 可能没有报告；应以脚本弹窗、FL MCP REPORT 日志及卷帘中实际音符为准。

完整生成与增量编曲的区别

不要把增量路径的手动操作要求套到完整 FLP 生成路径上。fl_undo 可用于 FL 支持撤销的编辑；新建文件、模板配置、后台任务与文件导出不属于 FL 的撤销历史。

听觉诊断

fl_listen 会播放并录制工程；fl_diagnose 将“闷、刺耳、浑、薄”等描述与频谱/响度测量关联，再返回可检查的参数和混音目标。有参考音频时可做相对比较；没有参考时采用声部经验范围，不能视为统一审美标准。

7. 工具与参数参考

7.1 完整还原的三个入口

fl_recreation_config：所有参数可省略；无参数时只读。

fl_recreate_music：path 必填，其余按模式选择。

统一任务实际处理的片段要求为 0.1–600 秒，且包含有效、可听信号。auto 对短音乐片段可能判断为音色，需要显式指定 kind: "song"。

fl_recreation_status：

7.2 全部 31 个工具

完整 JSON Schema 以服务器 tools/list 响应及 server.py 为准。服务器同时提供 fl_arranging_guide prompt，说明工作顺序和单位。

7.3 命令行与本地 HTTP

.\fl-studio-mcp.exe --version
.\fl-studio-mcp.exe ports
.\fl-studio-mcp.exe doctor --json
.\fl-studio-mcp.exe call fl_get_project
.\fl-studio-mcp.exe call fl_recreation_config
.\fl-studio-mcp.exe serve --transport http --host 127.0.0.1 --port 47821

不带子命令时启动 stdio MCP 服务，等待客户端协议消息；看起来没有交互提示是正常的。call <工具> <JSON参数> 用于调试，注意所在 shell 的 JSON 引号规则。

HTTP 端点为 http://127.0.0.1:47821/mcp，提供 JSON 响应，不提供 SSE 推送。可让多个客户端共享一个本地服务，但 FL 写入和试听任务应串行操作。该接口没有用户认证，面向本机使用，不应直接暴露到公网。

当前协商支持 MCP 协议版本 2025-06-18、2025-03-26、2024-11-05；不代表已经逐一验证所有客户端版本。

8. 数据、任务与恢复

同一数据目录包含：

data/
├── recreation-config.json
├── templates/<sha256>.flp
├── recreation-jobs/recreate-<id>/
│   ├── request.json
│   ├── state.json
│   ├── process.json
│   └── worker.log
├── analyses/
├── audio/
└── exports/

任务状态为 queued、running、waiting_fl_close、done、cancelled 或 error。结果包含 phase、progress、message、artifacts、状态与日志文件路径。

• 同一数据目录同时只允许一个待完成的完整还原任务，避免互相操作 FL。

• fl_recreate_music 的任务由独立进程执行，断开工具连接不会结束它。更换客户端时必须使用同一数据目录才能查到任务。

• 这不是断电自动续跑系统；工作进程崩溃会被标记为错误。除等待关闭 FL 的任务外，错误任务需要排查后新建。

• 旧版 fl_match_sound 的运行中 job_id 仅属于原服务器进程。需要跨连接运行时，应使用统一入口；完成后可通过保存的 match_id 取回结果。

• 工具不自动删除旧音频、任务目录或模板。结束任务后可自行备份、清理；不要删除运行中任务的文件。

音频分析与搜索在本机执行，服务器不主动上传音频到外部识别服务。AI 客户端会收到工具返回的文字、测量与文件路径；客户端或模型服务如何处理这些内容，取决于你使用的客户端配置。

9. 工作原理

flowchart TD
    A[支持 MCP 的 AI 客户端] --> B[stdio / 本地 HTTP 服务器]
    B --> C[持久化任务管理器]
    C --> D{任务类型}
    D -->|整曲| E[音频分析：速度 / 段落 / 和弦 / 鼓 / 低音]
    E --> F[模板编辑器生成 FLP 与 MIDI]
    F --> G[FL 原生命令行渲染]
    G --> H[完整性验证与 A/B 音频]
    D -->|音色| I[搜索插件参数]
    B --> J[实时工程控制]
    I --> K[WinMM / loopMIDI / FL Bridge]
    J --> K
    K --> L[FL Studio 插件与工程]
    L --> M[WASAPI 录音与音色特征比较]
    M --> I

实时控制通过 MIDI SysEx 传输 JSON 消息。桥接脚本运行在 FL 内，执行宿主允许的 MIDI 脚本 API。音频分析、文件操作和后台进程运行在外部 Python/EXE 中。

FL 的实时脚本接口不能覆盖所有播放列表和音符编辑需求，因此整曲路径使用保守的 FLP 模板编辑器：识别已验证的 FL 24 结构，保留未知块和插件状态，只修改所需音符、片段、标记与速度。遇到不支持的版本或不合要求的模板时拒绝生成。

渲染调用 FL 官方命令行接口。若导出文件已完整写完，但 FL 在退出阶段停留，工具会等待文件稳定并确认已关闭，再验证音频；通过后只清理本任务启动的批量渲染进程。Image-Line 导出文档

10. 常见问题

提交 Issue 时，建议附上版本、Windows/FL 版本、复现步骤和相关错误日志。分享前删除个人路径、项目名和不准备公开的素材信息。

11. 开发、测试与打包

11.1 目录结构

src/fl_studio_mcp/
├── server.py                 # MCP 工具定义、JSON-RPC、使用指引
├── tools.py                  # FL 会话、参数标准化与实时命令
├── recreation.py             # 配置、持久任务、进程启动、取消/继续
├── recreation_worker.py      # 完整还原流程、渲染与验证
├── flp.py                    # FL 24 保守模板编辑器
├── midi_export.py            # 完整 MIDI 导出
├── ears.py / listen.py        # 听觉工具、播放与录音
├── match.py / rebuild.py      # 音色优化、增量编曲
├── audio/                    # DSP、歌曲分析、音色特征、Windows 录音
├── midi_transport.py         # WinMM SysEx 通信
├── http_transport.py         # 本地 HTTP 传输
├── setup_wizard.py           # loopMIDI、FL 和客户端配置
├── diagnostics.py            # 连接与版本诊断
└── fl/                       # 装入 FL 的桥接和钢琴卷帘脚本
tests/                        # 离线测试及合成音频生成器
scripts/build_exe.py          # Windows 单文件 EXE 打包
examples/                     # MCP 配置和工具参数示例

11.2 离线测试与安装验证

在 Windows 源码目录、已安装依赖的 Python 环境中执行：

python -m unittest discover -s tests -p 'test_*.py' -v
python -m pip check
python -m pip wheel --no-deps --wheel-dir dist .

测试不需要启动 FL；覆盖消息分片与多客户端隔离、参数校验、连接恢复、钢琴卷帘生命周期、音色搜索、FLP 未知块保留、完整编曲、任务持久化、取消、渲染文件检查等。

GitHub Actions 在 Windows runner 上分别验证 Python 3.10 与 3.12 的安装、离线测试和 wheel 构建。CI 不安装商业 FL，不代表每次提交都经过实机播放测试。

11.3 合成音频与分析评测

python tests/make_samples.py
python tests/evaluate.py

生成器创建带标准答案的测试素材，包括 120 BPM 流行、124 BPM house、85 BPM lo-fi、单音 bass/pluck/pad/lead 及明暗 lead 对比。文件写入 samples/，默认不提交 Git。评测用于研究分析误差，不能代替真实商业混音上的广泛评估。

11.4 构建 EXE

已安装项目依赖的 Python 环境中：

python -m pip install 'pyinstaller>=6.9,<7'
python scripts/build_exe.py
python scripts/collect_licenses.py --output dist/third-party-licenses

默认输出 dist/fl-studio-mcp.exe。也可以把构建缓存和交付文件放在指定磁盘：

New-Item -ItemType Directory -Force E:\FL-MCP\temp | Out-Null
$env:TEMP = 'E:\FL-MCP\temp'
$env:TMP = $env:TEMP
$env:PYINSTALLER_CONFIG_DIR = 'E:\FL-MCP\temp\pyinstaller-cache'
python scripts/build_exe.py --dist-dir E:\FL-MCP\release --work-dir E:\FL-MCP\build

独立后台 worker 设置 PYINSTALLER_RESET_ENVIRONMENT=1，避免父进程退出后丢失临时解包文件；启动 FL 时会隔离 PyInstaller 的 DLL 搜索目录。发布前应验证父 MCP 进程关闭后任务仍能完成。PyInstaller 相关说明

发布 EXE 之外还提供 wheel 和 SHA-256 校验文件。仓库不提交本地 MCP 私人配置、运行日志、用户工程、参考音频或商业素材。

12. 验证结果与能力边界

0.6.0 在开发机器的 FL Studio 24.2.1 上完成了以下验证：

这些是特定环境、模板与合成素材的功能验证，不是对任意音乐的还原质量保证。当前限制包括：

• 假设 4/4 拍；和弦为三和弦，复杂转位、延伸和弦、自由速度和不规则拍号可能不准确。

• 鼓与 bass 从混音中启发式估计，可能漏音、误判或发生八度偏差；段落名称也只是估计。

• 尚未实现人声、独立主旋律转录、音源分离及逐分轨自动音色匹配。

• 整曲音色取决于模板；单音色搜索只能调整宿主公开的参数，不能保证自动找到原曲音源。

• 当前只验证 FL 24 模板结构；即使实时 API 可连接其他版本，也不表示其工程格式可写。

• 文件验证不等于旋律、和声、节奏或听感正确，结果需要在 FL 中试听与修改。

欢迎通过可复现样例、测试和 Issue 改进这些环节。

13. 许可证与参考资料

本项目代码采用 MIT License。第三方依赖遵循各自的许可证；发布 EXE 附带第三方许可证说明。本项目是独立工具，与 Image-Line 无隶属或官方背书关系，FL Studio 及相关商标属于其权利人。

• Image-Line MIDI Scripting API：FL 内控制接口。

• Image-Line 音频导出与命令行接口：原生渲染。

• Microsoft Application Loopback Audio：进程级录音机制和系统要求。

• PyFLP：FLP 格式研究参考；本项目使用独立模板编辑实现，没有将 PyFLP 作为依赖或捆绑其代码。

• PyInstaller：Windows EXE 打包及独立子进程处理。

• Model Context Protocol：工具连接协议。