# FL Studio Agent

Drive FL Studio from an AI agent.
`fl-studio-agent` is an MCP server, a Python SDK, and a native Bridge plugin: your agent writes notes, sets tempo, levels and plugin parameters, checks which channels sound, and renders the mix, in your own FL Studio.

<!-- install:start (generated by scripts/install_links.py; edit there) -->
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=fl-studio&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXB5dGhvbiIsIjMuMTIiLCJmbC1zdHVkaW8tYWdlbnQiXX0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=fl-studio&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--python%22%2C%223.12%22%2C%22fl-studio-agent%22%5D%7D)
[![Claude Desktop bundle](https://img.shields.io/badge/Claude_Desktop-Download_bundle-D97757?style=flat-square&logo=claude&logoColor=white)](https://github.com/origami-research/fl-studio-agent/releases/latest/download/fl-studio-agent.mcpb)
[![PyPI](https://img.shields.io/pypi/v/fl-studio-agent?style=flat-square)](https://pypi.org/project/fl-studio-agent/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/origami-research/fl-studio-agent/blob/main/LICENSE)

**Claude Code:**

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

## Quick start

You need FL Studio 2026 on macOS or Windows and [uv](https://docs.astral.sh/uv/getting-started/installation/).

1. **Install uv** if you don't have it.
   macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
   Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`, then install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html) and add two ports named exactly `FLMCP Req` and `FLMCP Res` (Windows has no virtual MIDI ports; macOS needs nothing).
2. **Set up FL Studio once.** Start FL once if you never have, close it, then run (on Windows, in a terminal opened as administrator, because FL's plugin folder is under Program Files):

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

   It installs the controller and note scripts, assigns the controller's MIDI ports, creates the agent's own project (`FLMCP Agent.flp`; your other projects are never touched), and downloads the prebuilt [Bridge plugin](https://github.com/origami-research/fl-studio-agent/blob/main/SETUP.md#the-bridge-plugin) for live writes and `render`, checking it against the release's SHA-256 sums.
   It is safe to rerun.
   To update later, run it with `fl-studio-agent@latest` in place of `fl-studio-agent` and restart FL and your client.
3. **Add the server to your client** with a button above or a config below, open FL Studio, and ask for "a 4-bar chord loop in A minor".

<details>
<summary><b>Claude Code</b></summary>

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

Check it with `claude mcp list`.
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Download [fl-studio-agent.mcpb](https://github.com/origami-research/fl-studio-agent/releases/latest/download/fl-studio-agent.mcpb) and open it (or drag it into Settings > Extensions).
Claude Desktop installs the package itself; you still run step 2 once, which also installs the Bridge plugin into FL.

Or add this to `claude_desktop_config.json` (Settings > Developer > Edit Config):

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

If Claude Desktop reports `spawn uvx ENOENT`, it cannot see your shell's PATH: replace `"uvx"` with the full path that `which uvx` (macOS) or `where uvx` (Windows) prints.
</details>

<details>
<summary><b>Cursor</b></summary>

Use the **Install in Cursor** button above, or add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "fl-studio": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "fl-studio-agent"
      ]
    }
  }
}
```
</details>

<details>
<summary><b>VS Code</b></summary>

Use the **Install in VS Code** button above, or run (macOS/Linux shell quoting):

```bash
code --add-mcp '{"name": "fl-studio", "type": "stdio", "command": "uvx", "args": ["--python", "3.12", "fl-studio-agent"]}'
```
</details>

<details>
<summary><b>Windsurf and other clients</b></summary>

Add the standard entry to the client's MCP config (Windsurf: `mcp_config.json`, see [its MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)):

```json
{
  "mcpServers": {
    "fl-studio": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "fl-studio-agent"
      ]
    }
  }
}
```
</details>

## Troubleshooting

Run the doctor while FL Studio is open:

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

It prints one JSON report of the control plane (controller script and MIDI ports), the note plane, and the agent project, with a `fix` for anything not connected.
The usual fixes: open FL Studio before your client starts the server; after an upgrade rerun step 2 with `fl-studio-agent@latest` (a stale controller is reported); on Windows, keep loopMIDI running with both ports.
Using the FL Studio trial? Set `FLMCP_FL_LICENSE=trial` in the server's `env`, because the trial cannot reopen saved projects.
`uvx --python 3.12 fl-studio-agent --version` prints the installed version.
<!-- install:end -->

## Tools

The server exposes five tools, one per job:

| Tool | Purpose |
| --- | --- |
| `run` | Execute Python against the FL SDK: write and clear notes, tempo, levels, parameters. Its docstring is the SDK cheatsheet. |
| `get_scene` | Read what FL has now: a compact musical summary, or the notes (`detail="notes"`, by channel and pattern). |
| `check` | Play a few bars and read FL's mixer meters: which channels sounded, their peaks, and why a silent one is silent. |
| `render` | Play the live arrangement once and record the mix to WAV. |
| `analyze` | Analyze a WAV deterministically. |

The working rhythm is write, check at milestones, render at the end.
Every result is what FL now has, so nothing needs waiting for, saving, or re-reading.
FL's transient refusals ("operation unsafe at current time", a busy control wire) are retried inside the engine; a model sees only errors it can act on.
Setup diagnostics are for the operator, not the model: `fl-mcp-doctor` prints the same report as JSON.

## How it works

Three complementary lanes: [`flpkit`](https://pypi.org/project/flpkit/) edits project files, the native Bridge plugin performs live host operations, and the MIDI controller script handles live controller operations.
[SETUP.md](SETUP.md) covers installing from a source checkout and building the Bridge.

## Development

For a disposable live smoke session, run `fl-mcp-dev-session`. For the local merge gate, run:

```bash
scripts/gate.sh
```

The gate is the authoritative test count and verification contract; see [docs/gate.md](docs/gate.md) for its current stages.

## Documentation

- [SETUP.md](SETUP.md): installation from source, the Bridge plugin, Windows.
- [docs/README.md](docs/README.md): current documentation map.
- [docs/24-coverage-map.md](docs/24-coverage-map.md): capability status.
- [RUNBOOK_E2E.md](RUNBOOK_E2E.md): end-to-end verification.