FL Studio MCP Server

# FL Studio MCP Server An MCP (Model Context Protocol) server that enables AI assistants to control FL Studio through MIDI communication and Piano Roll scripts. ## Features ### Transport Control - Play, pause, stop playback - Toggle recording - Set playback position - Get song length and position - Control loop mode (pattern/song) - Adjust playback speed ### Mixer Control - Get/set track volume and pan - Mute/solo tracks - Arm tracks for recording - Set track names and colors - Stereo separation control ### Channel Rack Control - List all channels - Get/set channel properties (volume, pan, name, color) - Mute/solo channels - Route channels to mixer tracks - Trigger MIDI notes in real-time - Step sequencer control (get/set grid bits) ### Plugin Control - List plugin parameters - Get/set parameter values - Navigate presets (next/previous) - Query plugin info ### Piano Roll Control - **Add notes** to the piano roll with precise timing - **Add chords** with a single command - **Delete specific notes** by MIDI number and time - **Clear all notes** from the piano roll - **Read piano roll state** to see all existing notes - Auto-triggering via keystroke (Cmd+Opt+Y on macOS, Ctrl+Alt+Y on Windows) ## Important Limitations ### Cannot Load Plugins The FL Studio scripting API does **not** support loading new VST/AU plugins. You can only control parameters of plugins that are already loaded in your project. ### Cannot Create Patterns There is no API to programmatically create new patterns. You can only work with existing patterns. ## Requirements - **FL Studio 20.7+** (MIDI Controller Scripting API) - **Python 3.10+** - **macOS** or **Windows** - macOS: IAC Driver (built-in, needs to be enabled) - Windows: [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html) ## Quick Installation The easiest way to install is using the provided setup script: ```bash # Clone the repository git clone https://github.com/your-username/fl-studio-mcp.git cd fl-studio-mcp # Run the setup script ./scripts/setup.sh ``` This will: 1. Guide you through enabling virtual MIDI ports (IAC Driver on Mac) 2. Install the FL Studio MIDI controller script 3. Install the Piano Roll script (ComposeWithLLM) 4. Install Python dependencies ## Manual Installation ### 1. Install Python Dependencies ```bash # Using uv (recommended) uv sync # Or using pip pip install -e . ``` ### 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](https://www.tobias-erichsen.de/software/loopmidi.html) 2. Create a virtual port (any name works) 3. Keep loopMIDI running while using FL Studio ### 3. Install FL Studio Scripts Copy the controller script to FL Studio's Hardware folder: ```bash # 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: ```bash # 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") 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): ```json { "mcpServers": { "fl-studio": { "command": "uv", "args": ["run", "--directory", "/path/to/fl-studio-mcp", "fl-studio-mcp"] } } } ``` Or for Claude Code, add to your MCP settings. ## Usage ### Running the Server Manually ```bash # 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 ## Available Tools ### 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 | ## Example Workflows ### Adjusting a Mix ```text "Set the volume of mixer track 1 to 80% and pan it slightly left" ``` ### Creating a Drum Pattern ```text "Create a basic kick pattern on channel 0 with kicks on steps 0, 4, 8, and 12" ``` ### Adding a Melody to Piano Roll ```text "Add a C major arpeggio starting at beat 0: C4, E4, G4, C5 - each note quarter duration" ``` ### Adding Chords ```text "Add a C major chord at beat 0, then F major at beat 2, then G major at beat 4" ``` ### Automating Plugin Parameters ```text "List the parameters of the plugin on channel 0 and set the filter cutoff to 50%" ``` ## 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) ### 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 This MCP server uses a hybrid approach: ```text ┌─────────────────┐ ┌─────────────────────────────────────────┐ │ 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) to trigger FL Studio script - Piano Roll script reads JSON and modifies notes ## Credits - [FL Studio API Stubs](https://github.com/IL-Group/FL-Studio-API-Stubs) - API documentation - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework - [mido](https://github.com/mido/mido) - MIDI library for Python - [calvinw/fl-studio-mcp](https://github.com/calvinw/fl-studio-mcp) - Piano Roll integration approach - [Image-Line](https://www.image-line.com/) - FL Studio ## License MIT