FL Studio Agent

FL Studio Agent

通过 AI Agent 操控 FL Studio。 fl-studio-agent 是一个 MCP 服务、Python SDK 和原生 Bridge 插件：你的 Agent 可以在你自己的 FL Studio 中编写音符、设置速度、音量和插件参数、检查哪些声道正在发声，并渲染混音。

Claude Code：

claude mcp add --scope user fl-studio -- uvx --python 3.12 fl-studio-agent

快速开始

你需要在 macOS 或 Windows 上安装 FL Studio 2026 和 uv。

1. 安装 uv（如果尚未安装）。 macOS：curl -LsSf https://astral.sh/uv/install.sh | sh。 Windows：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"，然后安装 loopMIDI，并添加两个名称必须完全为 FLMCP Req 和 FLMCP Res 的端口（Windows 没有虚拟 MIDI 端口；macOS 无需进行任何操作）。

2. 设置一次 FL Studio。 如果你从未启动过 FL Studio，请先启动一次，然后关闭它，再运行（在 Windows 上，请在以管理员身份打开的终端中运行，因为 FL 的插件文件夹位于 Program Files 下）：

   uvx --python 3.12 --from fl-studio-agent fl-mcp-install
   

   这会安装控制器和音符脚本、分配控制器的 MIDI 端口、创建 Agent 专用项目（FLMCP Agent.flp；绝不会触及你的其他项目），并下载用于实时写入和 render 的预构建 Bridge 插件，同时根据发行版的 SHA-256 校验和对其进行验证。 可以安全地重复运行。 之后如需更新，请将 fl-studio-agent 替换为 fl-studio-agent@latest 运行，然后重启 FL 和你的客户端。

3. 通过上方按钮或下方配置将服务添加到客户端，打开 FL Studio，并请求“制作一个 A 小调的 4 小节和弦循环”。

claude mcp add --scope user fl-studio -- uvx --python 3.12 fl-studio-agent

{
  "mcpServers": {
    "fl-studio": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "fl-studio-agent"
      ]
    }
  }
}

{
  "mcpServers": {
    "fl-studio": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "fl-studio-agent"
      ]
    }
  }
}

code --add-mcp '{"name": "fl-studio", "type": "stdio", "command": "uvx", "args": ["--python", "3.12", "fl-studio-agent"]}'

{
  "mcpServers": {
    "fl-studio": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "fl-studio-agent"
      ]
    }
  }
}

故障排除

在 FL Studio 运行时执行 doctor：

uvx --python 3.12 --from fl-studio-agent fl-mcp-doctor

它会输出一份 JSON 报告，涵盖控制平面（控制器脚本和 MIDI 端口）、音符平面和 Agent 项目，并为所有未连接的项目提供 fix。 常见的修复方法：在客户端启动服务之前先打开 FL Studio；升级后，使用 fl-studio-agent@latest 重新运行步骤 2（如果控制器已过时，报告会指出）；在 Windows 上，确保 loopMIDI 正在运行且包含两个端口。 正在使用 FL Studio 试用版？请在服务的 env 中设置 FLMCP_FL_LICENSE=trial，因为试用版无法重新打开已保存的项目。 uvx --python 3.12 fl-studio-agent --version 会显示已安装的版本。

工具

服务器提供五种工具，每种对应一项任务：

工作节奏是：编写，在关键节点检查，最后渲染。 每个结果都反映 FL 当前的状态，因此无需等待、保存或重新读取。 FL 的暂时性拒绝（“当前时刻无法安全执行操作”、控制线路繁忙）会在引擎内部重试；模型只会看到可采取措施处理的错误。 设置诊断面向操作者，而非模型：fl-mcp-doctor 会以 JSON 格式输出相同的报告。

工作原理

有三条互补的途径：flpkit 用于编辑项目文件，原生 Bridge 插件用于执行实时宿主操作，MIDI 控制器脚本用于处理实时控制器操作。 SETUP.md 介绍如何从源码检出版本进行安装，以及如何构建 Bridge。

开发

要进行一次临时的实时冒烟测试会话，请运行 fl-mcp-dev-session。要执行本地合并检查，请运行：

scripts/gate.sh

该检查是测试数量和验证约定的权威依据；当前阶段请参阅 docs/gate.md。

文档

• SETUP.md：从源码安装、Bridge 插件、Windows。
• docs/README.md：当前文档索引。
• docs/24-coverage-map.md：功能状态。
• RUNBOOK_E2E.md：端到端验证。