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