CryptoJones/FL-Studio-MCP-Server

谨以此项目献给 John Philip Sousa (1854–1932) —— “进行曲之王”
前“总统御用”美国海军陆战队乐队总监

Sousa 在 1880 至 1892 年间领导“总统御用”乐队，并谱写了美国进行曲的经典之作 —— 《星条旗永不落》 （美国国家进行曲）、《永远忠诚》（美国海军陆战队官方进行曲）以及《华盛顿邮报》。他发明了苏萨大号，并在录音技术普及之前，将进行曲乐队的旋律送入了每个美国人的耳中。他用整个乐团共同阅读同一总谱的方式构建音乐 —— 这正是本项目所要生成的：一个可编辑的多轨 FL 工程，而不是单调的混音文件。

本项目的兄弟项目是 Dix (VibeComposing) Analyzer， 该项目献给“统帅御用”乐队的 Maj. Brian Dix —— 他们是 As30p 工具链中与海军陆战队音乐相关的两个同名项目。

# FL-Studio-MCP-Server [](https://github.com/CryptoJones/FL-Studio-MCP-Server/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/CryptoJones/FL-Studio-MCP-Server) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](https://github.com/CryptoJones/FL-Studio-MCP-Server) 一个**允许 Claude Code（以及任何 MCP 客户端）与 FL Studio 交互的 MCP 服务器** —— 驱动运行中的 DAW，并以编程方式生成/编辑 FL 工程。 ## 为什么需要 FL Studio 没有暴露**任何外部的 REST / OSC / AppleScript API**。它唯一的编程接口是一个**内置的 Python API**（包含 14 个模块，427+ 个函数：如 `transport`, `mixer`, `channels`, `patterns`, `playlist`, `plugins` 等），该接口原本是设计给运行在 FL *内部* 的 MIDI 控制器脚本使用的。本项目对该接口进行了封装 —— 并加上了离线工程文件处理工具 —— 将它们转化为清晰易用的 MCP 工具。 ## 三大 API 路径 | 路径 | 模块 | 功能说明 | 运行环境 | 状态 | |-------|--------|--------------|------|--------| | **A — PyFLP** | `routes/pyflp_route.py` | 直接读取/写入 `.flp` 工程文件（速度、标题、元数据、通道名称）。 | 离线，无需运行 FL | ✅ **已实现** | | **B — Flapi** | `routes/flapi_route.py` | 外部客户端 -> FL 内部的服务器脚本 -> 调用 427 个函数的 API（transport, mixer, channels, hint, eval）。 | 实时运行，需打开 FL | ✅ **已实现**（需要在 FL 端进行设置） | | **C — Piano Roll** | `routes/script_route.py` | 一组 `flpianoroll` 脚本库，安装到 FL 的 Piano Roll 工具菜单中。 | 在 FL 中一次性运行 | ✅ **已实现** | 详细分类、链接和权衡分析：**[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。 ## 路径 A (PyFLP) —— 目前可用的功能 路径 A 是一个确定性的离线路径：**无需运行 FL Studio。** 新 工程是基于自带的 FL *空* 模板 （`src/fl_studio_mcp/templates/empty.flp`）生成的，因此生成的每一个 `.flp` 都能在 FL 中干净地打开。 服务器注册的工具： | Tool | 功能说明 | |------|--------------| | `flp_info(path)` | 检查 `.flp` 文件 —— FL 版本、PPQ、速度、标题/艺术家/流派/注释、通道与 Pattern 名称。 | | `flp_create(out_path, title?, tempo?, artists?, genre?, comments?)` | 使用指定的元数据（从空模板）创建一个新的 `.flp` 文件。 | | `flp_load_samples(out_path, samples, title?, tempo?, arrange?, stagger_bars?, …)` | 创建一个新的 `.flp`，为**每个音频文件生成一个 Sampler 通道** —— 每个切片都被加载（并命名）到 Channel Rack 中。在事件层级克隆模板的 Sampler，并为每个通道注入一个 `SamplePath`。如果设置 `arrange=true`，还会将每个音轨作为全长**Audio Clip 放置在 Playlist 上**（每个轨道一个，相隔 `stagger_bars` 的距离错开）—— 打开后就已经排列好了。 | | `flp_set_tempo(path, bpm, out_path?)` | 设置速度 (BPM)。可直接编辑原文件，或写入副本到 `out_path`。 | | `flp_set_metadata(path, title?, artists?, genre?, comments?, out_path?)` | 设置元数据；只有你传入的字段会被修改。 | | `flp_rename_channel(path, index, name, out_path?)` | 通过从 0 开始的索引重命名通道。 | 此外还有 `ping`（健康检查）和 `routes`（路径状态）。 **诚实地说明范围：** 路径 A v1 涵盖了从模板创建、检查以及元数据/速度/通道名称的编辑 —— 这正是 PyFLP 在往返写入操作中实际支持的功能范围。从头开始编排 *新* 的通道、Pattern 和音符并没有通过 PyFLP 的公开模型 API 暴露出来；这是**路径 B (Flapi)** 的工作，由 FL 本身去完成音符的制作。详见 [BACKLOG.md](BACKLOG.md)。 ## 路径 B (Flapi) —— 对运行中的 FL 进行实时控制 路径 B 通过 [Flapi](https://github.com/MaddyGuthridge/Flapi) 驱动**正在运行**的 FL Studio： 外部客户端通过虚拟 MIDI 端口（macOS IAC Driver，自动创建）与 FL 内部的服务器脚本通信，从而使得对 FL 脚本 API 的调用能够直接作用于实时会话。 FL 端的一次性设置： ``` pip install "fl-studio-mcp-server[live]" # flapi + FL API stubs # 然后，通过 MCP 工具 `fl_install_server`（或 `python -m flapi install`），并重启 FL ``` | Tool | 功能说明 | |------|--------------| | `fl_status` | 是否安装了 `live` 扩展？是否已连接？（安全操作 —— 永远不会触碰 MIDI） | | `fl_connect` | 通过 Flapi 连接到运行中的 FL（返回 FL 的 API 版本）。 | | `fl_install_server` | 将 Flapi 服务器安装到 FL 中（`flapi install`）；之后需重启 FL。 | | `fl_hint(message)` | 在 FL 的面板上显示提示信息 —— 最快的连通性冒烟测试。 | | `fl_transport(action)` | `play`（播放）/ `stop`（停止）/ `record`（录制）/ `toggle`（切换）播放控制。 | | `fl_get_tempo` | 获取当前工程速度 (BPM)。 | | `fl_mixer(index?, volume?)` | 读取轨道数量 / 读取轨道音量 / 设置轨道音量。 | | `fl_channels` | 列出 Channel Rack 中的通道名称。 | | `fl_eval_expr(expr)` | 逃生舱口：在实时 FL 中评估任意表达式（例如 `patterns.patternCount()`）。 | 每一个路径 B 的工具都**具备优雅降级功能** —— 如果没有 `live` 扩展或没有运行中的 FL，它会 返回一个结构化的 `{"ok": false, "error": …}`，而不是导致服务器崩溃。 ## 路径 C (Piano Roll) —— 内置脚本库 路径 C 提供了现成的 **[Piano Roll 脚本](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/pianoroll_scripting_api.htm)** （`flpianoroll`），并将它们安装到 FL 的 *Piano roll scripts* 文件夹中，它们会 出现在 Piano Roll 的 Tools（扳手图标）下拉菜单中： | Script | 功能说明 | |--------|--------------| | `transpose` | 将音符平移 N 个半音。 | | `humanize` | 为音符加入细微的随机时间/力度变化，营造真人演奏的感觉。 | | `strum` | 随时间推移依次展开和弦中的音符，就像吉他扫弦一样。 | | `note_repeats` | 带有时间/音高/力度衰减偏移的音符回声效果。 | | `scale_fill` | 生成一组取自特定音阶（大调/小调/调式/五声音阶）的连续音符。 | | Tool | 功能说明 | |------|--------------| | `piano_scripts_list` | 列出内置的脚本及其摘要。 | | `piano_scripts_describe(name)` | 显示脚本的完整源码。 | | `piano_scripts_install(dest?)` | 将它们复制到 FL 的 Piano roll scripts 文件夹中。 | ## 状态 **三大路径均已实现并经过测试。** 路径 A、路径 B 的错误返回机制以及路径 C 的 脚本和安装程序均由 pytest 测试套件覆盖（无需 FL）；实时路径 B 调用 以及在 FL 内部执行脚本需要结合 FL Studio 并完成上述一次性设置。详见 **[BACKLOG.md](BACKLOG.md)** / GitHub 的 **Issues** 标签页。 ## 目录结构 - `src/fl_studio_mcp/server.py` —— MCP 服务器；负责注册各路径的工具。 - `src/fl_studio_mcp/routes/` —— 每个 API 路径对应一个模块：`pyflp_route` (A), `flapi_route` (B), `script_route` (C)。 - `src/fl_studio_mcp/templates/empty.flp` —— 内置的 FL *空* 模板（路径 A 的基础文件）。 - `src/fl_studio_mcp/piano_scripts/*.pyscript` —— 内置的路径 C Piano Roll 脚本。 - `src/fl_studio_mcp/_compat.py` —— 在现代 CPython 上运行的 PyFLP 兼容层。 - `tests/` —— pytest 测试套件（包含路径 A 往返测试、路径 B 错误路径测试、路径 C 脚本和安装程序测试；不需要 FL）。 - `docs/` —— 架构与研究笔记。 - `BACKLOG.md` —— 任务清单，与 Issues 同步。 ## 环境要求 - Python **3.11 或 3.12**（PyFLP 2.2.1 暂不支持 3.13+）。 - FL Studio 2025 (25.x) —— 用于 *打开* 路径 A 生成的工程，并且（包含 `live` 扩展时）支持路径 B/C。 ## 安装与运行 ``` pip install -e . # or pip install -e ".[test]" for the test deps fl-studio-mcp # starts the MCP server (stdio) ``` ### 在 Claude Code 中注册 将以下内容添加到你的 MCP 配置文件（如 `.mcp.json`）中： ``` { "mcpServers": { "fl-studio": { "command": "fl-studio-mcp" } } } ``` 然后，在 Claude Code 中执行： ``` Create an FL project "The Stars and Stripes Forever" at ~/Music/sousa.flp, 120 BPM, artist As30p. ``` ## 测试 ``` pip install -e ".[test]" pytest -q ``` 该测试套件覆盖了全部三个路径，且不需要 FL Studio：**路径 A** 端到端测试 （创建、检查、就地设置速度并指定新路径保存、元数据、通道重命名、 对照内置模板进行往返重新解析）；**路径 B** 错误边界测试 （缺少扩展 / 无法连接 FL 时返回清晰的错误，而不是崩溃）；以及**路径 C** （对每个内置的 `.pyscript` 进行语法检查，验证是否符合 FL 的 `createDialog`/`apply` 契约，并测试安装程序）。CI 会在每次推送/提交 PR 时在 Python 3.11 和 3.12 环境下运行测试 （`.github/workflows/ci.yml`）。 ## 开源许可 Apache-2.0 —— 详见 [LICENSE](LICENSE)。 *与 Dix 共同直播构建。As30p / Ronin 48.*

自豪地来自内布拉斯加州。Go Big Red! 🌽 https://xkcd.com/2347/

标签：AI音乐, Claude, CVE检测, FL Studio, MCP Server, PyFLP, 安全规则引擎, 网络调试, 自动化, 逆向工具, 音乐制作