Metadata-Version: 2.5
Name: fl-studio-agent
Version: 0.1.2
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.8.1
Requires-Dist: mcp>=2.0.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pip>=24.0
Requires-Dist: python-rtmidi>=1.5.0
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

<!-- 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 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

`run` (Python against the FL SDK; its docstring is the SDK cheatsheet), `get_scene` (what FL has now), `check` (play a few bars and read which channels sounded), `render` (record the mix to WAV), and `analyze` (WAV analysis).
The full description is in the [repository README](https://github.com/origami-research/fl-studio-agent#tools).
