fl-studio-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Run Python in FL Studio's interpreter with every API module in scope. Assign to |
| 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 |
| Capture FL's window to a PNG with |
| Click at a window-relative position. |
| Send a real keystroke. Needed where the API has no equivalent: |
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 |
| 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; |
| 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. |
| Rank several clips by closeness to a reference layer or clip and explain the ranking. |
| Draw a fixed-scale mel spectrogram PNG, the reference stacked above. |
| 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. |
| Tier 1: score clips on the profile's contrastive prompt pairs, as deltas against the approved references. Needs the model setup below. |
| Record the owner's verdict on a clip, with the owner's own words. |
| Put FL back if a crashed or interrupted listen left state behind. Nothing plays. |
| 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 |
| 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 asFL64.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 |
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.pyre-tests all three after an FL update.Pattern length is in steps, 16 per bar, not beats as the reference says.
selectToolis inplaylist, notui.patterns.clearPatternopens 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.pyis 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
Layoutwere 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.shThis will:
Install uv if not present
Install Python dependencies
Guide you through enabling virtual MIDI ports (IAC Driver on Mac)
Install the FL Studio MIDI controller script
Install the Piano Roll script (ComposeWithLLM)
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)
Open Audio MIDI Setup (search in Spotlight)
Press Cmd+2 or go to Window > Show MIDI Studio
Double-click on IAC Driver
Check "Device is online"
Click Apply
Windows (loopMIDI)
Download and install loopMIDI
Create a virtual port (any name works)
Optional, for the pipeline: create a second port with
FLStudioNotesin 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.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 backupFL 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
Restart FL Studio (if it's running)
Go to Options > MIDI Settings
Under Input, find your virtual MIDI port (e.g., "IAC Driver Bus 1" or your loopMIDI port)
Set the Controller type to FLStudioMCP
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-mcpPiano Roll Workflow
Open FL Studio and select a channel
Open the Piano Roll (F7 or double-click the channel)
The first time, manually run the script: Tools > Scripting > ComposeWithLLM
After that, the MCP tools will auto-trigger the script
Building a Song with the Pipeline (Windows)
Open FL Studio with the playlist visible
Check the playlist and browser coordinates in
Layout(src/fl_studio_mcp/pipeline.py) against a screenshot of your layoutRun the demo, optionally passing the bar to start at:
uv run python scripts/demo_pipeline.py 1It 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 |
| Connect/reconnect to FL Studio |
| Get connection status |
Transport
Tool | Description |
| Start/pause playback |
| Stop playback |
| Toggle recording |
| Get playback/recording state |
| Set playback position |
| Get song duration |
| Switch between pattern/song mode |
| Adjust playback speed (0.25x-4x) |
Mixer
Tool | Description |
| Get number of mixer tracks |
| Get track details |
| List all tracks |
| Set track volume |
| Set track pan |
| Mute/unmute track |
| Solo/unsolo track |
| Arm track for recording |
| Rename track |
| Set track color |
| Adjust stereo width |
Channels
Tool | Description |
| Get number of channels |
| Get channel details |
| List all channels |
| Get selected channel |
| Select/deselect channel |
| Select channel exclusively |
| Trigger MIDI note (real-time) |
| Set channel volume |
| Set channel pan |
| Mute/unmute channel |
| Solo/unsolo channel |
| Rename channel |
| Set channel color |
| Route to mixer track |
| Get step sequencer step |
| Set step sequencer step |
| Get full pattern |
| Set full pattern |
Plugins
Tool | Description |
| Check if plugin exists |
| Get plugin name |
| Get parameter count |
| List all parameters |
| Get parameter value |
| Set parameter value |
| Get preset count |
| Next preset |
| Previous preset |
| Get plugin color |
Piano Roll
Tool | Description |
| Add notes to the piano roll |
| Add a chord (multiple notes at same time) |
| Delete specific notes |
| Clear all notes |
| Read current piano roll notes |
| Manually trigger the FL Studio script |
| Get piano roll system info |
| 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_noteis 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"
Ensure FL Studio is running
Check that the FLStudioMCP controller is enabled in MIDI Settings
On Mac, verify IAC Driver is enabled in Audio MIDI Setup
On Windows, verify loopMIDI is running
Restart FL Studio after enabling the controller
"Timeout waiting for FL Studio response"
Make sure FL Studio is in focus
Check the Script output window in FL Studio (View > Script output)
Verify the controller is receiving MIDI (look for activity in MIDI Settings)
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
First time: manually run Tools > Scripting > ComposeWithLLM in FL Studio
On macOS: grant Accessibility permissions when prompted
Ensure FL Studio is in focus when triggering
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
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
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
Added in this fork:
fl_execandfl_introspect_apiuse the same MIDI + JSON link, with two new handlers in the controller scriptThe 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 |
| Run the MCP server |
| Lint the codebase |
| Lint and auto-fix |
| 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 installerCredits
karl-andres/fl-studio-mcp - the project this started from
calvinw/fl-studio-mcp - Piano Roll integration approach
FL Studio API Stubs - API documentation
FastMCP - MCP server framework
mido - MIDI library for Python
Image-Line - FL Studio
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
Read and edit DAW projects as an agent, save native Logic projects, convert projects between DAWs
Create, co-edit, analyze, publish, and export collaborative step-sequencer sessions through MCP.
Autonomous music production for AI agents with MIDI generation, QC and provenance.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLM agents to capture screenshots, control mouse/keyboard, and manage windows on desktop platforms, primarily Windows, via an MCP server.161MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 PyPI8MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityBmaintenanceEnables 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.-