# fl-mcp

Local MCP server for FL Studio 2026 on macOS. Requires Node 22+.

## Setup

```sh
git clone https://github.com/ae5n/fl-mcp.git
cd fl-mcp
npm install
npm run setup
```

On macOS, open **Audio MIDI Setup → Window → Show MIDI Studio → IAC Driver**,
enable **Device is online**, and ensure `Bus 1` and `Bus 2` exist.

Then open **FL Studio → Options → MIDI settings**:

- `Bus 1` output: Port `11`
- `Bus 2` output: enable, Port `10`
- `Bus 1` input: select `fl-mcp`, enable, Port `10`
- `Bus 2` input: disable

Add the config printed by setup, or register the server with your client:

```sh
# Claude Code
claude mcp add fl-mcp -- node /absolute/path/to/fl-mcp/dist/mcp/main.js

# Codex
codex mcp add fl-mcp -- node /absolute/path/to/fl-mcp/dist/mcp/main.js
```

In **System Settings → Privacy & Security → Accessibility**, allow the app that
launches fl-mcp (Codex, Claude, or Terminal), then restart that app.

Open the target Piano Roll and run **Tools → Scripts → fl-mcp bridge** once.
Keep that Piano Roll open for exact note operations.

## Tools


| Area       | MCP tools                                                                | Operations                                            |
| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------- |
| Session    | `fl_session_probe`, `fl_session_revision`                                | Capabilities and stale-write revision                 |
| Project    | `fl_project_state`, `fl_tempo_set`                                       | Project context and tempo                             |
| Transport  | `fl_transport_state`, `fl_transport_control`, `fl_transport_seek`        | Play, stop, record, and seek                          |
| Channels   | `fl_channel_list`, `fl_channel_set`                                      | Routing, levels, pan, mute, and selection             |
| Patterns   | `fl_pattern_list`, `fl_pattern_select`                                   | List and select patterns                              |
| Mixer      | `fl_mixer_list`, `fl_mixer_set`                                          | Levels, pan, mute, and names                          |
| Playlist   | `fl_playlist_tracks`                                                     | Read track names                                      |
| Plugins    | `fl_plugin_instances`, `fl_plugin_parameters`, `fl_plugin_parameter_set` | List, search, read, and set parameters                |
| Automation | `fl_automation_parameter_event`                                          | Send resolved parameter events                        |
| Piano Roll | `fl_pianoroll_snapshot`, `fl_pianoroll_patch`, `fl_pianoroll_replace`    | Page, add, edit, delete, or replace notes and markers |


Requests are typed and serialized; tools cannot execute arbitrary Python or FL
event IDs. Mutations use stale-state checks and readback.

Automation storage requires FL to record **Notes and automation**; the first
record command may open FL's recording prompt. Playlist tracks are read-only;
FL does not expose Automation Clip or Playlist clip CRUD.

## Transport

```text
MCP stdio → user-only local socket → resident companion
                                      ├─ SysEx → FL controller
                                      └─ atomic files → Piano Roll bridge
```

The companion owns the MIDI ports and serializes writes. Piano Roll exchange
stays inside FL's script directory and does not use the clipboard.

## Development

```sh
npm run build
npm test
npm run typecheck
```

After changing source code, run `npm run build` and restart Codex or Claude.
Run `npm run setup` instead when a script under `fl/` changes.

License: MIT