Repository navigation
Releases
Releases · geezoria/FLStudioMCP
fLMCP 0.4.0
Works on FL Studio 2025 and 2026 again, on MCP SDK 2.x, and installs with one
command.
Breaking
- The PyPI distribution is now
flmcp-studio.fl-studio-mcpon PyPI belongs
to a different project, and PyPI rejectsflmcpas too similar tof1-mcp.
Install withuvx flmcp-studio install. The command isflmcp(plus a
flmcp-studioalias for uvx). The import package (fl_studio_mcp) and the
legacyfl-studio-mcpcommand stay. The MCP client entry is renamed to
flmcp, andflmcp installremoves the oldfl-studio-mcpentries. - The TCP bridge is gone. FL Studio 2025/2026 run controller scripts in a
sandboxed sub-interpreter without threads or sockets (#1). The bridge now
uses a file transport (protocol 2). Re-runflmcp installso FL gets the new
device_FLStudioMCP.py. - Requires
mcp>=2.3,<3. The server moved from the removed
mcp.server.fastmcptomcp.server.mcpserver(#3).
Added
- Claude Desktop bundle (
mcpb/).npx @anthropic-ai/mcpb pack mcpb
buildsflmcp-<version>.mcpb, a one-click install for Claude Desktop that
runs the PyPI package with uv and exposes the tool groups and the timeout as
extension settings. CI validates and packs it on every push. - File + MIDI-wake transport (protocol 2). Atomic command and response
files, a once-a-second heartbeat with bridge/FL/API versions, a
cross-process lock,time_nsids that survive clock rollback, stale-command
suppression on FL start, batched actions, and fail-fast "bridge unavailable"
when FL isn't listening. An optional CC 119 / ch 16 wake through a loopMIDI
port namedfLMCPbrings round-trips down to tens of milliseconds.
Thanks to @cgradusov (#2) and @marcostolosa (#4, #5), whose PRs first proved
a file-based transport inside FL 2025's sandbox. flmcpCLI.flmcp installcopies the FL scripts into FL's real user data folder,
creates the loopMIDI port, assigns the controller, and registers the server
with Claude Desktop, Claude Code, Cursor and VS Code, backing up configs
first.flmcp doctorchecks files, outdated scripts, the MIDI port and controller
assignment, FL process, heartbeat, live ping and version mismatch.flmcp configprints per-client snippets, including Codex.flmcp uninstallremoves everything again.- Running
flmcpwith no arguments starts the server, souvx flmcp-studiojust
works.
- The FL scripts ship inside the wheel, so installing from PyPI/uvx needs no
git clone. - MCP 2 features. Every tool has a title and read-only / destructive /
idempotent annotations, and returns structured output. - 6 guided prompts: Make a Beat, Write a Chord Progression, Hum to
Melody, Flip Audio to Drum & Bass, Review a Mix, Project Overview. - Toolsets:
FLMCP_TOOLSETS(all,core,leanor any group list) and
FLMCP_DISABLE_TOOLS. The newfl_list_toolsetstool lists them. - FL Studio 2026 API support (gated, so FL 2024/2025 keep working):
pattern_set_length, which really sets the length now (in bars, beats or
steps; FL's unit turned out to be steps, not beats as documented).- New
pattern_cleartool, which empties a pattern's notes and steps. pattern_clonecan copy into a chosen pattern (dest_index).- New
channel_get_swing/channel_set_swingtools for the Channel rack swing. - New
ui_show_pickertool, which opens the plugin or project picker. project_metadatareports title, author and genre.mixer_countreportsinsert_count.
fl_introspecttool, backed by the newmeta.introspectbridge action. It
lists which scripting functions the running FL build exposes, with optional
docstrings.fl_pingwarns when the bridge script inside FL is older than the server and
tells you how to update it.server.jsonfor the official MCP Registry (io.github.geezoria/flmcp).- CI on Windows/macOS/Linux × Python 3.10/3.12/3.13 with a wheel smoke test,
issue and PR templates,CONTRIBUTING.md,SECURITY.md,AGENTS.md, and a
generateddocs/TOOLS.md(scripts/gen_tools_doc.py). docs/FL_API_2026.md: FL 2026 scripting API changes (API 45).scripts/live_check.py(replacessmoke_test.py) runs every read-only tool
against a running FL through the real MCP server. With--writeit also runs
the edits, each one restored afterwards, a pattern lifecycle, and every
piano-roll tool on a scratch pattern. 104 checks pass on FL 26.1.7.
Changed
scripts/install_windows.ps1/uninstall_windows.ps1are thin wrappers
aroundflmcp install/flmcp uninstall.- Bridge, CLI and FL user data folder detection honour FL's Shared data
registry setting andFLMCP_BRIDGE_DIR. - Rewrote README, ARCHITECTURE and LIMITATIONS for the new transport.
- Piano-roll tools need no setup on Windows. The server runs ComposeWithLLM
from the piano roll's Tools menu with posted window messages, so it doesn't
depend on the script being the selected one, on focus, or on Ctrl+Alt+Y. FL
doesn't come to the front and the mouse and keyboard stay free. It falls
back to the hotkey, and results report which one ran intrigger
(tools_menuorhotkey).
Fixed
- Tool errors reach the model. MCP 2 replaces any exception that isn't a
ToolErrorwith "Error executing tool X", so the model never learned that a
bridge call failed with, say, a bad index, or that a call timed out. Every
tool now passes its error text on. - Mixer tools check the track against the project's inserts. FL 2026 projects
can have fewer than 125. FL raised a bare "Index out of range" for most
calls, andchannel_route_to_mixersilently routed to the last insert
instead. channel_solocan unsolo. On FL 26.1.7 a secondsoloChannel()call
doesn't undo a solo, so the other channels stayed muted. The bridge now
unmutes every channel, as FL's own Solo button does. Found by an end-to-end
run through Claude Code.transport_playreports the state it switched to. FL'sisPlaying()lags
within a callback, so the tool used to answeris_playing: falseright after
starting playback.- When ComposeWithLLM doesn't answer, the piano-roll tools empty the request
queue. Queued edits used to run on the next unrelated script run. pattern_clearno longer returnscleared: falseafter a successful clear.
FL 26.1.7 clears without asking for confirmation.- Pattern tools no longer treat
patterns.patternCount()as the highest
pattern index. It is 0 in a fresh project even though Pattern 1 exists,
sopattern_set_lengthand friends rejected valid patterns, and
pattern_create/pattern_listcould miss or overwrite patterns after a
gap. Indices are now checked againstpatternMax(), and "in use" means
having content or a custom name. pattern_clonereports the index FL really cloned into.flmcp doctorno longer reports a working bridge as broken on FL 2026.
There, FL never calls the script'sOnIdle, so the heartbeat only refreshes
on MIDI wakes. Doctor now pings through a wake, and it treats a missing
loopMIDI port as a real problem.- Transport tools now act on the song while a plugin window has focus. FL
sendstransport.start/stop/recordto a focused plugin that has its own
transport, such as Edison, sotransport_stopcould leave the song playing.
The bridge first moves focus to the Playlist and reportsrefocused_from.
The automation recorder does the same. - Automation recording works on FL 2026. Arming Record opens FL's "What would
you like to record?" prompt. The recorder used to start playback in the same
callback, which closed the prompt and cancelled the arm. Its points then
failed with "Operation unsafe at current time", and the end of the run could
leave Record armed. The bridge now runs the recording as a state machine over
ticks. It arms, waits for the prompt to be answered, starts playback, and
counts point times from there. It retries a point that hits "unsafe", then
stops and disarms without ever arming Record again. On Windows the server
answers the prompt with Notes and automation, and the result says so.
Verified on FL 26.1.7: a mixer-volume ramp recorded into the pattern and
played back. The heartbeat reports the recorder's state, and the client
keeps waking FL until the run ends. - Plugin tools work on FL 2026.
plugins.getParamValueStringtakes at most 4
arguments there, not the 5 in the API stubs, soplugin_get_paramand
plugin_set_paramfailed with aTypeError.plugin_paramsswallowed the
same error and returned an empty list. The bridge now handles both forms, and
plugin_paramsreports a failing parameter instead of dropping it. On a
sampler or an empty slot the tools returnno plugin at …with a hint.
plugin_set_paramreturns the value it set, because FL reports a mixer
effect's old value until the next callback. Verified on FLEX and on
Emphasizer. playlist_list_markerslists marker names through
arrangement.getMarkerName. It used to return nothing. FL exposes no marker
positions.- "Operation unsafe at current time" errors now name the FL dialog that is in
the way (Windows).transport_recordreports when the record prompt opened,
andui_focused_windowreturnsfocused_form_caption. flmcp doctorreports when more than one FL Studio instance is running.
They share the bridge folder, so they race for commands and a single call
can run in both.flmcp installnow really assigns the controller. It also writes the MIDI
input'sType="-3", which marks a script controller. Without it FL ignored
ScriptFolder, and users had to pick fLMCP Bridge in MIDI Settings by
hand.flmcp doctorwarns when an input names the bridge with another Type.
Verified end to end on FL 26.1.7: with FL closed, the registry was reset to a
fresh state, then install ran and ...