Metadata-Version: 2.5
Name: fl-studio-agent
Version: 0.1.7
Summary: MCP server for controlling FL Studio's piano roll
Project-URL: Homepage, https://github.com/origami-research/fl-studio-agent
Project-URL: Repository, https://github.com/origami-research/fl-studio-agent
Project-URL: Documentation, https://github.com/origami-research/fl-studio-agent/tree/main/docs
Author: Origami Research
Maintainer: Origami Research
License-Expression: MIT
License-File: LICENSE
Keywords: fl-studio,mcp,music-production,piano-roll
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Artistic Software
Requires-Python: >=3.11
Requires-Dist: flpkit==0.9.0
Requires-Dist: librosa>=0.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp>=2.0.0
Requires-Dist: mido>=1.3
Requires-Dist: music21>=9.1
Requires-Dist: numpy>=2.0.0
Requires-Dist: pillow>=11.0
Requires-Dist: pip>=24.0
Requires-Dist: pyloudnorm>=0.1
Requires-Dist: python-rtmidi>=1.5.0
Requires-Dist: scipy>=1.13
Requires-Dist: soundfile>=0.12
Requires-Dist: truststore>=0.10
Requires-Dist: watchdog>=6.0.0
Description-Content-Type: text/markdown

# FL Studio Agent

Drive FL Studio from an AI agent: an MCP server that writes notes, sets tempo, levels and plugin parameters, checks which channels sound, and renders the mix, in your own FL Studio.
Source, docs, and the native Bridge plugin: https://github.com/origami-research/fl-studio-agent

<p align="center">
  <img src="https://raw.githubusercontent.com/origami-research/fl-studio-agent/main/docs/media/demo.gif" alt="Claude writes a lo-fi beat in FL Studio and plays it to check the mixer meters before it renders" width="800">
</p>

<!-- mcp-name: io.github.origami-research/fl-studio-agent -->

<!-- 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 open a new terminal so `uvx` is on your PATH.
   Also on Windows, install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html), add two ports named exactly `FLMCP Req` and `FLMCP Res`, and tick **Autostart loopMIDI** in its tray menu so the ports come back after a restart (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), the native FL effect the server requires to write notes 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. **Open the agent project in FL Studio**: File > Open, `FLMCP Agent.flp` in FL's Projects folder (`Documents/Image-Line/FL Studio/Projects`).
   It carries the Bridge on its Master insert; in any other song there is no Bridge running, so notes and `render` are refused.
4. **Add the server to your client** with a button above or a config below, 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 the server requires 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 (the Bridge), and the agent project.
Its `status` is `ok` only when all of them are connected, and `not_ready` otherwise, with a `fix` for each one that is not.
The usual fixes: open `FLMCP Agent.flp` in FL Studio before your client starts the server (the doctor reports no running Bridge when another song is open, and rerunning step 2 when none is installed); 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`, and answer **No** when FL asks to save `FLMCP Agent.flp`: the trial cannot reopen a song it saved. If it was saved, delete it and rerun step 2, which creates it again.
`uvx --python 3.12 fl-studio-agent --version` prints the installed version.
<!-- install:end -->

## Tools

One tool, `run`: Python against the live FL session through the `fl` object (read the song, write, read the meters, render and listen), with numpy, scipy, librosa and matplotlib installed. Its description is the whole manual.
The full description is in the [repository README](https://github.com/origami-research/fl-studio-agent#tools).
