Skip to main content
Glama
fl-studio-mcp

fl-studio-mcp

by KindaMAD-hav

fl-studio-mcp-KindaMAD

Started as a fork of karl-andres/fl-studio-mcp. Karl's project is the base of this one: the MCP server, the MIDI + JSON bridge, the controller script that runs inside FL Studio, and the transport, mixer, channel, plugin and piano roll tools. His project in turn credits calvinw/fl-studio-mcp for the piano roll approach.

This fork adds what an agent needs to build a full arrangement in FL Studio on Windows without anyone at the keyboard: a tool that runs Python inside FL, screenshot and click tools, a Win32 layer that drives FL's UI without moving the cursor, and a pipeline that turns a song spec into patterns and playlist clips.

What this fork adds

Run code inside FL Studio

Tool

Description

fl_exec

Run Python in FL Studio's interpreter with every API module in scope. Assign to _result to return a value. Stdout and tracebacks come back too.

fl_introspect_api

List what the running FL build actually exposes, module by module. FL ships no type stubs, and the reference is wrong in places.

Every other tool wraps one API call, so a new capability used to mean a new controller handler, a reinstall and a reload. fl_exec skips that, and one call with a loop in it replaces dozens of tool calls.

See and click (Windows)

Tool

Description

fl_screenshot

Capture FL's window to a PNG with PrintWindow. Works when FL is covered and does not take focus. Optional crop and downscale.

fl_click

Click at a window-relative position.

fl_press_key

Send a real keystroke. Needed where the API has no equivalent: ui.enter() does nothing to a browser node, a real Enter loads it.

Hear what FL plays (Windows)

Optional hearing extra. FL plays the project aloud in real time and the server records FL's own audio from Windows (process loopback), one pass for the master and, if asked, one per mixer track or layer with the other tracks muted. Nothing is rendered or exported. FL is put back exactly as it was found and the restore is verified. The analysis is numeric and explained: loudness, true peak, harshness, brightness, envelope, stereo, key, tempo and forbidden pitch classes, each against your approved reference audio, with a distance and a plain-English summary.

Tool

Description

fl_listen

Play a window of the open project (by bar) and capture the master and optional per-track or per-layer passes. About 15 s per pass, at most 90 s of playback per call; continue_listen adds the passes that did not fit. Analyses the captures by default.

fl_analyze_audio

Measure a WAV or a captured pass, with deltas, flags and the distance to the approved references when a profile is set. Never talks to FL.

fl_compare_audio

Rank several clips by closeness to a reference layer or clip and explain the ranking.

fl_spectrogram

Draw a fixed-scale mel spectrogram PNG, the reference stacked above.

fl_audition

Play one pattern once per candidate sound (each a mixer track) and return a ranked shortlist with reasons. Never adds or deletes notes, patterns or channels.

fl_score_vibe

Tier 1: score clips on the profile's contrastive prompt pairs, as deltas against the approved references. Needs the model setup below.

fl_record_verdict

Record the owner's verdict on a clip, with the owner's own words.

fl_hearing_restore

Put FL back if a crashed or interrupted listen left state behind. Nothing plays.

fl_hearing_status

What hearing can do on this machine: extra, capture methods, profiles, baselines, tier-1 models, a pending restore.

Install it with uv sync --extra hearing and add "--extra", "hearing" to the server's args (see Manual Installation). Without the extra the tools still register and return the install hint.

Profiles. A profile names the project's tempo, key, layers, the mixer tracks that make up each layer, and the approved reference audio (per-layer takes, stems, mixes). Copy src/fl_studio_mcp/hearing/profiles/example.json to ~/.fl-studio-mcp/hearing/profiles/<name>.json, set name to the file name and replace every C:/path/to/... with your own files. Without a profile the analysis still runs, but nothing is compared and no flag is evaluated. Then build the reference baseline once (and again after changing the references):

uv run --extra hearing python -m fl_studio_mcp.hearing.baseline --profile <name>

--status reports the baseline state without building. fl_hearing_status lists the profiles and their baselines.

Tier 1 models (optional). fl_score_vibe and the use_models options use audio-text models (CLAP, optionally MERT) in their own venv at ~/.fl-studio-mcp/venvs/hearing-models (Python 3.11, CPU torch). They are never dependencies of this package. Set them up from a terminal:

uv run python scripts/setup_hearing_models.py --dry-run     # show the steps, change nothing
uv run python scripts/setup_hearing_models.py --profile <name>

It creates the venv with uv (or py -3.11), installs the pinned stack from scripts/hearing_models/requirements.txt, downloads pinned model revisions, runs a smoke test and a benchmark, and pre-embeds the profile's references. Every step is idempotent and resumable. Disk: about 0.6 GB for the venv and 1.6 GB for CLAP (download plus a local copy); --with-mert adds about 0.4 GB. CLAP (laion/larger_clap_music_and_speech) is Apache-2.0. MERT (m-a-p/MERT-v1-95M, CC-BY-NC-4.0) and NVIDIA's Music Flamingo (non-commercial licence) are opt-in local analysis aids whose non-commercial weights you download yourself; nothing in this repo downloads Music Flamingo, and no tool uses it. A tier-1 call adds up to 120 s; scores are deltas against your approved references, never a verdict.

The design, with every threshold and the reasons for it, is in docs/specs/2026-11-11-hearing-design.md.

Multi-channel piano roll writes

Tool

Description

fl_compose_arrangement

Write notes to several channels in one call. Selects each channel, focuses its piano roll, writes the notes and triggers the script.

The piano roll trigger (Ctrl+Alt+Y) used to land in whichever window had focus, usually the terminal running the server, so FL never ran the script. It now finds FL's window, focuses it, sends the key and gives focus back. It also waits on a completion check instead of a fixed delay.

Win32 automation layer: utils/fl_window.py

  • Finds FL's main window by its process (FL64.exe), not its title, so an Explorer window or browser tab that mentions FL Studio never matches. It also reports the executable path, because FL 2025 and 2026 install side by side and both run as FL64.exe.

  • Per-monitor DPI aware, so coordinates hold on scaled and mixed-DPI displays.

  • Clicks, drags, scrolls and keys are posted straight to FL's message queue. The cursor does not move and your foreground window stays put.

  • Detects FL's modal dialogs, which block its script thread and stall the control link. Dismissing them is the one path that uses the real cursor, and it puts the cursor back afterwards.

Song pipeline: pipeline.py

FLPipeline().build(song) takes a Song (tempo, named patterns holding notes per channel, and an arrangement of (pattern, playlist_track, start_bar)) and builds it in FL:

Part

How

Tempo, patterns, channel selection

Scripting API

Notes

Streamed over MIDI and captured with general.dumpScoreLog

Playlist clips

Posted clicks on the playlist grid

Instruments

FL's browser and ADD menu, plus a real Enter keystroke

Loading an instrument is the only step that needs focus. scripts/verify_hands_free.py samples the cursor during a build to check that nothing else moves it. scripts/demo_pipeline.py builds a two-section drum arrangement and is the place to start.

The pipeline reads the scripting API version from general.getVersion() and gates the newer calls on it (patterns.setPatternLength, playlist.selectTool, patterns.clearPattern, patterns.duplicatePatternData).

What FL's scripting API can't do

Measured on FL Studio 2025 (API 38) and 2026 (API 45). Full notes are in docs/PIPELINE.md.

  • No function places a playlist clip, creates a channel or inserts a mixer FX slot. The pipeline does the first two through FL's UI. FX insertion is not built. scripts/check_api_gain.py re-tests all three after an FL update.

  • Pattern length is in steps, 16 per bar, not beats as the reference says.

  • selectTool is in playlist, not ui.

  • patterns.clearPattern opens a modal dialog on every call, which blocks the script thread until it is answered. Ticking "Remember my choice" once stops it.

  • PyFLP is not a way around this on FL 2025. Its writer produces files FL refuses to open, and its reader misparses FL 2025's 80-byte playlist clip records. flp_splice.py is kept as the record of that investigation.

Status

Working end to end from a Song: tempo, patterns, notes, instruments through the ADD menu, and clip placement.

Not done yet:

  • Composition helpers (scales, voicings, groove templates). Every note in the demo scripts is written out by hand.

  • Mix pass. build() does not set mixer levels or plugin parameters yet, although the tools for both work.

  • Revision loop. build(reuse_slots=True) rebuilds in place, but spec diffing is not written.

  • Playlist and browser coordinates in Layout were measured at 2560x1380. Re-measure them from a screenshot if your layout differs, or clips land on the wrong bar without any error.

Related MCP server: omni-computer-use

Requirements

  • FL Studio 20.7+ (MIDI Controller Scripting API). The pipeline was built on FL Studio 2025 (25.2.3) and 2026 (26.1.4).

  • Python 3.10+

  • Windows for everything this fork adds. The original tools also run on macOS.

    • Windows: loopMIDI

    • macOS: IAC Driver (built in, needs to be enabled)

Quick Installation

The setup script is written for macOS. On Windows it cannot set up MIDI or the controller script, so it prints those steps instead. They are covered under Manual Installation.

# Clone the repository
git clone https://github.com/KindaMAD-hav/fl-studio-mcp-KindaMAD.git
cd fl-studio-mcp-KindaMAD

# Run the one-command installer
./install.sh

This will:

  1. Install uv if not present

  2. Install Python dependencies

  3. Guide you through enabling virtual MIDI ports (IAC Driver on Mac)

  4. Install the FL Studio MIDI controller script

  5. Install the Piano Roll script (ComposeWithLLM)

  6. Configure Claude Desktop or Claude Code automatically

Manual Installation

1. Install Python Dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

For the hearing tools, install the optional extra as well:

uv sync --extra hearing

# Or using pip
pip install -e ".[hearing]"

2. Enable Virtual MIDI Ports

macOS (IAC Driver)

  1. Open Audio MIDI Setup (search in Spotlight)

  2. Press Cmd+2 or go to Window > Show MIDI Studio

  3. Double-click on IAC Driver

  4. Check "Device is online"

  5. Click Apply

Windows (loopMIDI)

  1. Download and install loopMIDI

  2. Create a virtual port (any name works)

  3. Optional, for the pipeline: create a second port with FLStudioNotes in its name. Notes stream over it so a long burst does not wake the controller script for every note. Without it the pipeline uses the control port.

  4. Keep loopMIDI running while using FL Studio

3. Install FL Studio Scripts

On Windows, with FL Studio closed:

python scripts/install_controller.py          # show what would change
python scripts/install_controller.py --apply  # install, keeping a backup

FL runs a copy of the controller script from its settings folder, and nothing keeps that copy in step with the repo. Re-run this after any change to fl_controller/device_FLStudioMCP.py and after every FL Studio update.

Or copy the controller script to FL Studio's Hardware folder by hand:

# macOS
mkdir -p ~/Documents/Image-Line/FL\ Studio/Settings/Hardware/FLStudioMCP
cp fl_controller/device_FLStudioMCP.py ~/Documents/Image-Line/FL\ Studio/Settings/Hardware/FLStudioMCP/

# Windows
mkdir "%USERPROFILE%\Documents\Image-Line\FL Studio\Settings\Hardware\FLStudioMCP"
copy fl_controller\device_FLStudioMCP.py "%USERPROFILE%\Documents\Image-Line\FL Studio\Settings\Hardware\FLStudioMCP\"

Copy the Piano Roll script:

# macOS
cp scripts/ComposeWithLLM.pyscript ~/Documents/Image-Line/FL\ Studio/Settings/Piano\ roll\ scripts/

# Windows
copy scripts\ComposeWithLLM.pyscript "%USERPROFILE%\Documents\Image-Line\FL Studio\Settings\Piano roll scripts\"

4. Configure FL Studio

  1. Restart FL Studio (if it's running)

  2. Go to Options > MIDI Settings

  3. Under Input, find your virtual MIDI port (e.g., "IAC Driver Bus 1" or your loopMIDI port)

  4. Set the Controller type to FLStudioMCP

  5. Enable the port (click to highlight it)

5. Configure Claude

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "fl-studio": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fl-studio-mcp-KindaMAD", "fl-studio-mcp"]
    }
  }
}

Or for Claude Code, add the same server to your MCP settings.

With the hearing extra, add "--extra", "hearing" to the args, so uv run keeps the extra installed:

"args": ["run", "--directory", "/path/to/fl-studio-mcp-KindaMAD", "--extra", "hearing", "fl-studio-mcp"]

Usage

Running the Server Manually

# Using uv
uv run fl-studio-mcp

# Or after installation
fl-studio-mcp

Piano Roll Workflow

  1. Open FL Studio and select a channel

  2. Open the Piano Roll (F7 or double-click the channel)

  3. The first time, manually run the script: Tools > Scripting > ComposeWithLLM

  4. After that, the MCP tools will auto-trigger the script

Building a Song with the Pipeline (Windows)

  1. Open FL Studio with the playlist visible

  2. Check the playlist and browser coordinates in Layout (src/fl_studio_mcp/pipeline.py) against a screenshot of your layout

  3. Run the demo, optionally passing the bar to start at:

uv run python scripts/demo_pipeline.py 1

It prints the project state before the build, then each pattern and clip it created.

Available Tools

The transport, mixer, channel, plugin and piano roll tools below are from the original project. fl_compose_arrangement and the scripting, vision and hearing tools are described above.

Connection

Tool

Description

fl_connect

Connect/reconnect to FL Studio

fl_connection_status

Get connection status

Transport

Tool

Description

fl_play

Start/pause playback

fl_stop

Stop playback

fl_record

Toggle recording

fl_get_transport_status

Get playback/recording state

fl_set_song_position

Set playback position

fl_get_song_length

Get song duration

fl_set_loop_mode

Switch between pattern/song mode

fl_set_playback_speed

Adjust playback speed (0.25x-4x)

Mixer

Tool

Description

fl_get_mixer_track_count

Get number of mixer tracks

fl_get_mixer_track_info

Get track details

fl_get_all_mixer_tracks

List all tracks

fl_set_track_volume

Set track volume

fl_set_track_pan

Set track pan

fl_mute_track

Mute/unmute track

fl_solo_track

Solo/unsolo track

fl_arm_track

Arm track for recording

fl_set_track_name

Rename track

fl_set_track_color

Set track color

fl_set_stereo_separation

Adjust stereo width

Channels

Tool

Description

fl_get_channel_count

Get number of channels

fl_get_channel_info

Get channel details

fl_get_all_channels

List all channels

fl_get_selected_channel

Get selected channel

fl_select_channel

Select/deselect channel

fl_select_one_channel

Select channel exclusively

fl_trigger_note

Trigger MIDI note (real-time)

fl_set_channel_volume

Set channel volume

fl_set_channel_pan

Set channel pan

fl_mute_channel

Mute/unmute channel

fl_solo_channel

Solo/unsolo channel

fl_set_channel_name

Rename channel

fl_set_channel_color

Set channel color

fl_route_channel_to_mixer

Route to mixer track

fl_get_grid_bit

Get step sequencer step

fl_set_grid_bit

Set step sequencer step

fl_get_step_sequence

Get full pattern

fl_set_step_sequence

Set full pattern

Plugins

Tool

Description

fl_is_plugin_valid

Check if plugin exists

fl_get_plugin_name

Get plugin name

fl_get_plugin_param_count

Get parameter count

fl_get_plugin_params

List all parameters

fl_get_plugin_param_value

Get parameter value

fl_set_plugin_param_value

Set parameter value

fl_get_preset_count

Get preset count

fl_next_preset

Next preset

fl_prev_preset

Previous preset

fl_get_plugin_color

Get plugin color

Piano Roll

Tool

Description

fl_send_notes

Add notes to the piano roll

fl_send_chord

Add a chord (multiple notes at same time)

fl_delete_notes

Delete specific notes

fl_clear_piano_roll

Clear all notes

fl_get_piano_roll_state

Read current piano roll notes

fl_trigger_script

Manually trigger the FL Studio script

fl_get_piano_roll_info

Get piano roll system info

fl_clear_request_queue

Cancel pending queued changes

Limitations

  • The dedicated tools only control what is already in the project. The scripting API cannot load plugins, add channels, place playlist clips or insert mixer FX slots. On Windows the pipeline adds channels and places clips through FL's UI (see above).

  • fl_trigger_note is real time only. Notes don't persist unless FL Studio is recording. Use the piano roll tools or the step sequencer for notes that stay.

  • Hearing captures on Windows only (WASAPI process loopback). On other platforms the analysis tools still work on WAV files.

  • Hearing plays FL out loud in real time: you hear every pass. FL must play through a normal Windows output device (not exclusive mode or a hardware ASIO driver), and it must be stopped when a listen starts.

  • Turn off Windows audio enhancements and headset effects (spatial sound, virtual surround, DTS and similar) on the output device FL plays through. They act on the captured audio and corrupt the measurements.

  • A listen with per-track passes mutes and unmutes mixer tracks, so FL marks the project changed (it asks to save on close) even though everything is put back. A master-only listen leaves a clean project clean.

  • One live caller at a time: while a listen or audition runs it holds the FL bridge, and other FL tools wait or get "FL bridge busy".

Example Workflows

Adjusting a Mix

"Set the volume of mixer track 1 to 80% and pan it slightly left"

Creating a Drum Pattern

"Create a basic kick pattern on channel 0 with kicks on steps 0, 4, 8, and 12"

Adding a Melody to Piano Roll

"Add a C major arpeggio starting at beat 0: C4, E4, G4, C5 - each note quarter duration"

Adding Chords

"Add a C major chord at beat 0, then F major at beat 2, then G major at beat 4"

Automating Plugin Parameters

"List the parameters of the plugin on channel 0 and set the filter cutoff to 50%"

Querying Anything the Tools Don't Cover

"Use fl_exec to list every pattern with its name and length in bars"

Troubleshooting

"Not connected to FL Studio"

  1. Ensure FL Studio is running

  2. Check that the FLStudioMCP controller is enabled in MIDI Settings

  3. On Mac, verify IAC Driver is enabled in Audio MIDI Setup

  4. On Windows, verify loopMIDI is running

  5. Restart FL Studio after enabling the controller

"Timeout waiting for FL Studio response"

  1. Make sure FL Studio is in focus

  2. Check the Script output window in FL Studio (View > Script output)

  3. Verify the controller is receiving MIDI (look for activity in MIDI Settings)

  4. Look for a modal dialog in FL. One blocks the script thread and every command times out until it is answered.

FL behaves like the controller code is out of date

It probably is. Run python scripts/install_controller.py to see the difference between the repo and the copy FL loads, then --apply with FL closed.

Pipeline clips land on the wrong bar or lane

The Layout coordinates no longer match your screen. Take an fl_screenshot, find bar 1 and bar 2 on the ruler and the first two track labels, and update Layout.

Piano Roll script not triggering

  1. First time: manually run Tools > Scripting > ComposeWithLLM in FL Studio

  2. On macOS: grant Accessibility permissions when prompted

  3. Ensure FL Studio is in focus when triggering

  4. Try pressing Cmd+Opt+Y (macOS) or Ctrl+Alt+Y (Windows) manually

No MIDI ports available

  • macOS: Enable IAC Driver in Audio MIDI Setup

  • Windows: Install and run loopMIDI

Architecture

The original project uses a hybrid approach:

┌─────────────────┐     ┌─────────────────────────────────────────┐
│   MCP Client    │────▶│           FastMCP Server                │
│  (Claude, etc)  │     │                                         │
└─────────────────┘     │  ┌─────────────────┐  ┌──────────────┐  │
                        │  │ MIDI + JSON     │  │ Piano Roll   │  │
                        │  │ Tools           │  │ Tools (JSON) │  │
                        │  └────────┬────────┘  └──────┬───────┘  │
                        └───────────┼──────────────────┼──────────┘
                                    │                  │
                               MIDI + JSON        JSON Files +
                                    │              Keystroke
                                    ▼                  ▼
                        ┌─────────────────────────────────────────┐
                        │              FL Studio                   │
                        │  ┌──────────────┐  ┌──────────────────┐ │
                        │  │FLStudioMCP   │  │ Piano Roll Script│ │
                        │  │(MIDI Ctrl)   │  │ (ComposeWithLLM) │ │
                        │  └──────────────┘  └──────────────────┘ │
                        └─────────────────────────────────────────┘

How It Works

  1. Transport/Mixer/Channels/Plugins:

    • MCP server writes command to JSON file

    • Sends MIDI trigger note to FL Studio

    • FL Studio controller script reads JSON, executes API, writes response

    • MCP server reads response

  2. Piano Roll:

    • MCP server writes note requests to JSON file

    • Sends keystroke (Cmd+Opt+Y / Ctrl+Alt+Y) to trigger FL Studio script

    • Piano Roll script reads JSON and modifies notes

  3. Added in this fork:

    • fl_exec and fl_introspect_api use the same MIDI + JSON link, with two new handlers in the controller script

    • The vision tools and the pipeline also post Win32 messages directly to FL's window

    • The pipeline streams notes over MIDI (a second port if there is one) and reads them back with general.dumpScoreLog

Development

Prerequisites

  • Python 3.10+

  • uv (recommended)

Setup

# Install all dependencies including dev extras
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Available Commands

Command

Description

uv run fl-studio-mcp

Run the MCP server

uv run ruff check .

Lint the codebase

uv run ruff check --fix .

Lint and auto-fix

uv run pytest

Run tests

Project Structure

fl-studio-mcp-KindaMAD/
├── fl_controller/
│   └── device_FLStudioMCP.py    # FL Studio MIDI controller script (runs inside FL Studio)
├── docs/
│   └── PIPELINE.md              # Pipeline design and the measured API capability map
├── scripts/
│   ├── setup.sh                 # FL Studio script installer
│   ├── install_mcp_for_claude.sh # Claude config installer
│   ├── install_controller.py    # Sync the controller script into FL (Windows)
│   ├── ComposeWithLLM.pyscript  # Piano Roll script (runs inside FL Studio)
│   ├── demo_pipeline.py         # Build a two-section arrangement from a Song
│   ├── check_api_gain.py        # Re-test the API walls after an FL update
│   ├── verify_hands_free.py     # Check a build never moves the cursor
│   ├── flp_validate.py          # Walk and compare .flp event streams
│   └── probe_*, diag_*, test_*  # Probes and diagnostics used to map the API
├── src/fl_studio_mcp/
│   ├── server.py                # FastMCP server entry point
│   ├── pipeline.py              # Song spec to FL project
│   ├── flp_splice.py            # Byte-level .flp clip editing (investigation record)
│   ├── tools/                   # MCP tool implementations
│   │   ├── channels.py
│   │   ├── mixer.py
│   │   ├── piano_roll.py
│   │   ├── plugins.py
│   │   ├── scripting.py         # fl_exec, fl_introspect_api
│   │   ├── transport.py
│   │   └── vision.py            # fl_screenshot, fl_click, fl_press_key
│   └── utils/
│       ├── connection.py        # FL Studio connection wrapper
│       ├── fl_trigger.py        # Piano roll keystroke trigger
│       ├── fl_window.py         # Win32 window lookup, focus and posted input
│       ├── midi_connection.py   # MIDI + JSON communication layer
│       └── screenshot.py        # PrintWindow capture
├── fl_api_report.json           # Live API surface from probe_fl_api.py, the baseline for check_api_gain.py
└── install.sh                   # One-command installer

Credits

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM agents to capture screenshots, control mouse/keyboard, and manage windows on desktop platforms, primarily Windows, via an MCP server.
      16
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Windows desktop automation via MCP, allowing AI agents to control mouse, keyboard, and screen capture with the same interface as Anthropic's computer-use tool.
      64 PyPI
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to capture multi-monitor screenshots with coordinate grids and perform mouse, keyboard, scrolling, dragging, and window-management actions on Windows via MCP tools or CLI. It provides pixel-accurate desktop automation for computer-use agents.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control and interact with a local Windows computer through authenticated MCP tools, including file operations, shell commands, process management, HTTP requests, and system/media inspection.
      -