fl-mcp

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

Setup

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:

# 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

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

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