Skip to content

Releases

fLMCP 0.4.0

Choose a tag to compare

@github-actions github-actions released this 22 Nov 21:26

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-mcp on PyPI belongs
    to a different project, and PyPI rejects flmcp as too similar to f1-mcp.
    Install with uvx flmcp-studio install. The command is flmcp (plus a
    flmcp-studio alias for uvx). The import package (fl_studio_mcp) and the
    legacy fl-studio-mcp command stay. The MCP client entry is renamed to
    flmcp, and flmcp install removes the old fl-studio-mcp entries.
  • 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-run flmcp install so FL gets the new
    device_FLStudioMCP.py.
  • Requires mcp>=2.3,<3. The server moved from the removed
    mcp.server.fastmcp to mcp.server.mcpserver (#3).

Added

  • Claude Desktop bundle (mcpb/). npx @anthropic-ai/mcpb pack mcpb
    builds flmcp-<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_ns ids 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 named fLMCP brings 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.
  • flmcp CLI.
    • flmcp install copies 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 doctor checks files, outdated scripts, the MIDI port and controller
      assignment, FL process, heartbeat, live ping and version mismatch.
    • flmcp config prints per-client snippets, including Codex.
    • flmcp uninstall removes everything again.
    • Running flmcp with no arguments starts the server, so uvx flmcp-studio just
      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, lean or any group list) and
    FLMCP_DISABLE_TOOLS. The new fl_list_toolsets tool 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_clear tool, which empties a pattern's notes and steps.
    • pattern_clone can copy into a chosen pattern (dest_index).
    • New channel_get_swing / channel_set_swing tools for the Channel rack swing.
    • New ui_show_picker tool, which opens the plugin or project picker.
    • project_metadata reports title, author and genre.
    • mixer_count reports insert_count.
  • fl_introspect tool, backed by the new meta.introspect bridge action. It
    lists which scripting functions the running FL build exposes, with optional
    docstrings.
  • fl_ping warns when the bridge script inside FL is older than the server and
    tells you how to update it.
  • server.json for 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
    generated docs/TOOLS.md (scripts/gen_tools_doc.py).
  • docs/FL_API_2026.md: FL 2026 scripting API changes (API 45).
  • scripts/live_check.py (replaces smoke_test.py) runs every read-only tool
    against a running FL through the real MCP server. With --write it 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.ps1 are thin wrappers
    around flmcp install / flmcp uninstall.
  • Bridge, CLI and FL user data folder detection honour FL's Shared data
    registry setting and FLMCP_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 in trigger
    (tools_menu or hotkey).

Fixed

  • Tool errors reach the model. MCP 2 replaces any exception that isn't a
    ToolError with "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, and channel_route_to_mixer silently routed to the last insert
    instead.
  • channel_solo can unsolo. On FL 26.1.7 a second soloChannel() 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_play reports the state it switched to. FL's isPlaying() lags
    within a callback, so the tool used to answer is_playing: false right 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_clear no longer returns cleared: false after 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,
    so pattern_set_length and friends rejected valid patterns, and
    pattern_create / pattern_list could miss or overwrite patterns after a
    gap. Indices are now checked against patternMax(), and "in use" means
    having content or a custom name.
  • pattern_clone reports the index FL really cloned into.
  • flmcp doctor no longer reports a working bridge as broken on FL 2026.
    There, FL never calls the script's OnIdle, 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
    sends transport.start/stop/record to a focused plugin that has its own
    transport, such as Edison, so transport_stop could leave the song playing.
    The bridge first moves focus to the Playlist and reports refocused_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.getParamValueString takes at most 4
    arguments there, not the 5 in the API stubs, so plugin_get_param and
    plugin_set_param failed with a TypeError. plugin_params swallowed the
    same error and returned an empty list. The bridge now handles both forms, and
    plugin_params reports a failing parameter instead of dropping it. On a
    sampler or an empty slot the tools return no plugin at … with a hint.
    plugin_set_param returns 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_markers lists 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_record reports when the record prompt opened,
    and ui_focused_window returns focused_form_caption.
  • flmcp doctor reports 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 install now really assigns the controller. It also writes the MIDI
    input's Type="-3", which marks a script controller. Without it FL ignored
    ScriptFolder, and users had to pick fLMCP Bridge in MIDI Settings by
    hand. flmcp doctor warns 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 ...
Read more