FL Studio MCP Mac

FL Studio MCP Mac

面向 macOS 的 FL Studio MCP 桥接程序。它向 Claude Desktop、Claude Code、Cursor 和其他支持 MCP 的工具等 MCP 客户端开放 FL Studio 的传输控制、混音器、通道、MIDI 导出和钢琴卷帘音符应用工作流。

这是一个 Alpha MVP，范围有意限定在 FL Studio 文档化的 Python MIDI 脚本和钢琴卷帘脚本 API 内。不保证完整的无界面 FL Studio 自动化功能。

为什么要做这个项目

目前大多数 FL Studio MCP 项目都面向 Windows。macOS 通过 CoreMIDI 使用虚拟端口的路径更简洁，而且 FL Studio 支持在 macOS 上使用基于 Python 的 MIDI 脚本。本项目将这些能力整合为一个小型本地 MCP 服务和配套的 FL Studio 脚本。

支持的功能

• 通过 macOS 虚拟 MIDI 端口进行实时桥接。
• FL Studio 状态和运行状况检查。
• 传输控制：播放、停止、切换录音、倒回、歌曲/模式切换、切换节拍器。
• 更改速度。
• 读取混音器轨道并明确修改轨道。
• 读取 Channel Rack 并明确修改通道。
• 生成用于导入 FL Studio 的标准 MIDI 文件。
• 钢琴卷帘队列文件，以及用于插入持久音符的附带 .pyscript 脚本。

已知限制

• FL Studio 的 MIDI 脚本 API 并非完整的 DAW API。
• 此处未实现加载插件、加载任意音频文件以及渲染/导出。
• 持久音符写入通过附带的钢琴卷帘脚本完成。MCP 服务会将音符加入队列；你需要在目标钢琴卷帘中运行 Scripts > FL Studio MCP Apply。
• 实时桥接需要在 FL Studio 的 MIDI 设置中映射请求/响应端口。MCP 服务会启动一个单例本地 MIDI 守护进程，让 Claude Desktop、Claude Code 和终端测试共享 CoreMIDI 端点。

安装

在此仓库中：

python3 -m pip install .
flstudio-mcp-mac-install

安装程序会复制：

• device_FLStudioMCP.py 到 ~/Documents/Image-Line/FL Studio/Settings/Hardware/FLStudioMCP/
• FL Studio MCP Apply.pyscript 到 ~/Documents/Image-Line/FL Studio/Settings/Piano roll scripts/

在 macOS 上配置 FL Studio

1. 启动一次 MCP 服务，以启动本地 MIDI 守护进程并创建虚拟 CoreMIDI 端口：

   flstudio-mcp-mac
   

   端口出现后，你可以停止这个前台 MCP 进程。后台守护进程会让 FLStudioMCP Request 和 FLStudioMCP Response 端口持续可供所有 MCP 客户端使用。

2. 打开 FL Studio，并前往 Options > MIDI Settings。

3. 在输入列表中选择 FLStudioMCP Request。

4. 将 Controller type 设置为 FL Studio MCP Mac。

5. 将控制器输出设置为 FLStudioMCP Response。

6. 如有需要，重启 MCP 客户端。如果出现重复的 FLStudioMCP 端口，请退出旧的 MCP 服务进程，然后重新启动 v0.1.1+ 守护进程。

MCP 客户端配置

有关 Claude Desktop、Claude Code、Cursor、Windsurf、PyPI 和 MCP Registry 的详细设置，请参阅 docs/publishing.md。

Claude Desktop 配置示例：

{
  "mcpServers": {
    "flstudio-mcp-mac": {
      "command": "flstudio-mcp-mac"
    }
  }
}

对于命令不在 PATH 中的源码安装：

{
  "mcpServers": {
    "flstudio-mcp-mac": {
      "command": "python3",
      "args": ["-m", "flstudio_mcp_mac"]
    }
  }
}

MIDI 音符工作流

如果你想要可导入的常规 .mid 文件，请使用 fl_create_midi_file。

如果你想将音符应用到当前打开的钢琴卷帘中，请使用 fl_queue_piano_roll_notes：

1. 让 MCP 客户端将音符加入队列。
2. 在 FL Studio 中打开目标通道的钢琴卷帘。
3. 运行 Scripts > FL Studio MCP Apply。

音符格式：

[
  { "pitch": 60, "start": 0, "duration": 1, "velocity": 100 },
  { "pitch": 64, "start": 1, "duration": 1, "velocity": 96 },
  { "pitch": 67, "start": 2, "duration": 2, "velocity": 96 }
]

时间以拍为单位。MIDI 音高使用标准的 0-127 范围。

开发

python3 -m pip install ".[dev]"
PYTHONPATH=src pytest

设置 FLSTUDIO_MCP_BRIDGE=mock，即可使用确定性的内存 FL Studio 响应运行 MCP 服务，以进行协议测试：

FLSTUDIO_MCP_BRIDGE=mock python3 -m flstudio_mcp_mac

常规实时模式使用后台守护进程。如需低级调试，请设置 FLSTUDIO_MCP_BRIDGE=direct，让单个 MCP 进程直接占用虚拟 MIDI 端口。

实时 FL Studio 验证步骤请参阅 docs/testing.md。

协议

桥接程序通过第 16 通道的 MIDI 控制更改帧发送 base64 JSON：

• CC 120：帧开始
• CC 121：一个 base64 字符
• CC 122：帧结束

FL 脚本只接受已列入白名单的命令名称，并为每个请求返回一个 JSON 响应。

隐私

此服务完全在你的计算机上运行。它不会收集遥测数据，也不会在任何远程服务上存储数据。它只通过 macOS 虚拟 MIDI 端口（CoreMIDI）与你本地的 FL Studio 实例通信，并且只会在你指定的位置写入文件：生成的 MIDI 文件，以及本地 Music 文件夹下的 Piano Roll 队列 JSON。无需账户、API 密钥或网络连接，你在 FL Studio 中进行的任何操作都不会离开你的计算机。

制作方

由 Puya Ventures LLC 构建。我会构建定制 MCP 服务和 AI 集成。 联系我：[email protected] | 作品集：https://puyarahmanian.com

许可证

MIT。请参阅 LICENSE。