READMEmain

FL Studio MCP Integration v2.0

(macOS Only - Current Version)

This guide helps set up the FL Studio MCP (Model Context Protocol) integration v2.0, allowing AI control of FL Studio via MIDI.

Overview of Changes

Dual-protocol architecture:
- CC-based protocol for simple commands (play, stop, etc.)
- SysEx-based protocol for complex data-heavy operations (chord progressions, melodies, etc.)
Advanced music production features:
- Chord progression generation
- Melody creation based on scales
- Parameter automation
- Arrangement control
- Enhanced status feedback
Infrastructure improvements:
- More robust error handling
- Better MIDI communication
- Structured feedback mechanism
- Music theory implementation (scales, chords, progressions)

Current Status (as of YYYY-MM-DD - Please update date)

Working Features:

Based on initial testing, the following core functionalities are confirmed working:

Basic Commands:
- play_note: Playing individual MIDI notes.
- control_transport: Controlling playback (play/stop).
- select_pattern: Selecting patterns.
- add_audio_effect: Adding effects to mixer tracks.
Advanced Commands:
- create_notes: Create/clear notes (Implementation unclear)

Non-Functional / Under Development:

The following features are currently not working reliably or are pending implementation/debugging:

Basic Commands: create_track, load_instrument, set_tempo, set_mixer_level, select_channel, add_midi_effect.
Advanced Commands: create_chord_progression, create_melody, automate_parameter, set_arrangement, get_status.

Note: The status reflects the current state and may change with further development and debugging. create_chord_progression is notably non-functional due to missing controller implementation.

Setup Instructions

Step 1: Set up the IAC Driver in macOS

Open Audio MIDI Setup (you can find it in Applications/Utilities or search with Spotlight)
Click Window > Show MIDI Studio if the MIDI studio is not already visible
Double-click on the IAC Driver icon
Check Device is online
Create a port named IAC Driver MCP Bridge if it doesn't already exist
Click Apply and close the window

Step 2: Install the MCP Server

Clone the repository
Install the required Python packages:
```
pip install -r requirements.txt
```
or
```
uv install
```
Make sure flstudio_mcp_iac/server.py is in the correct location in the project structure

Step 3: Install the FL Studio Controller Script

Navigate to your FL Studio MIDI scripts folder on macOS: /Applications/FL Studio.app/Contents/Resources/FL/System/Hardware/
Create a new folder named FL Studio MCP Controller.
Copy device_flstudiocontroller.py into this new folder.

Step 4: Configure FL Studio

Open FL Studio
Go to Options > MIDI Settings
Find IAC Driver MCP Bridge in the input devices list
Enable it and select FL Studio MCP Controller v2.0 as the controller type
Make sure the port is enabled (highlighted)
Click Refresh if the controller doesn't appear immediately

Step 5: Run the MCP Server

Run the server using the provided script:
```
./run_flstudio_mcp.sh
```
or directly with:
```
python -m flstudio_mcp_iac.server
```
You should see log messages indicating that the server has started and connected to the IAC Driver port

New Features

Chord Progressions

Create chord progressions like C-G-Am-F directly in FL Studio:

# Create a C major chord progression
create_chord_progression(
    progression=["C", "G", "Am", "F"],
    duration_beats=4,
    channel=0,
    velocity=100
)

# Create a jazz progression with 7th chords
create_chord_progression(
    progression=["Cmaj7", "Dm7", "G7", "Cmaj7"],
    duration_beats=2
)

Melody Generation

(Note: create_melody is currently non-functional)

# Example: Create a melody in C major (Currently non-functional)
# create_melody(
#     scale="C major",
#     length=8,
#     channel=1,
#     velocity=90
# )

# Example: Create a pentatonic melody (Currently non-functional)
# create_melody(
#     scale="A pentatonicminor",
#     length=16,
#     channel=2,
#     seed=42  # Use a seed for reproducible melodies
# )

Parameter Automation

(Note: automate_parameter is currently non-functional)

# Example: Automate filter cutoff (Currently non-functional)
# automate_parameter(
#     track_index=1,
#     plugin_index=0,
#     parameter_index=12,  # Cutoff parameter
#     points=[(0, 0.2), (4, 0.8), (8, 0.4), (16, 0.2)]  # (time, value) pairs
# )

Arrangement Control

(Note: set_arrangement is currently non-functional)

# Example: Set up a pattern sequence with loop points (Currently non-functional)
# set_arrangement(
#     pattern_sequence=[0, 1, 2, 3],
#     loop_start=0,
#     loop_end=4
# )

Enhanced Status Feedback

(Note: get_status is currently non-functional)

# Example: Get current status (tempo, playback state, etc.) (Currently non-functional)
# status = get_status()
# print(f"Current tempo: {status['data']['tempo']} BPM")
# print(f"Playing: {status['data']['playing']}")

API Reference

Basic Commands (CC-based)

Command	Description	Status
`create_notes(clear=False)`	Create/clear notes (Implementation unclear)	❌ Not Working
`play_note(note, velocity, duration)`	Play a single MIDI note	✅ Working
`create_track(name, track_type)`	Create a new track	❌ Not Working
`load_instrument(instrument_name, channel)`	Load an instrument	❌ Not Working
`set_tempo(bpm)`	Set the project tempo	❌ Not Working
`control_transport(action)`	Control playback (play/stop/record)	✅ Working
`select_pattern(pattern)`	Select a pattern by number	✅ Working
`set_mixer_level(track, level)`	Set mixer track volume	❌ Not Working
`select_channel(channel)`	Select a channel in the Channel Rack	❌ Not Working
`add_audio_effect(track, effect_type)`	Add an audio effect to a mixer track	✅ Working
`add_midi_effect(track, effect_type)`	Add a MIDI effect (Implementation unclear)	❌ Not Working

Advanced Commands (SysEx-based)

Command	Description	Status
`create_chord_progression(progression, duration_beats, channel, velocity)`	Create a chord progression	❌ Not Working
`create_melody(scale, length, channel, velocity, seed)`	Generate a melody based on a scale	❌ Not Working
`automate_parameter(track_index, plugin_index, parameter_index, points)`	Automate a plugin parameter	❌ Not Working
`set_arrangement(pattern_sequence, loop_start, loop_end)`	Set the pattern sequence and loop points	❌ Not Working
`get_status()`	Get detailed project status	❌ Not Working

Supported Chords

The system supports the following chord types:

Major: "C", "G", etc.
Minor: "Cm", "Am", etc.
Dominant 7th: "C7", "G7", etc.
Major 7th: "Cmaj7", "Gmaj7", etc.
Minor 7th: "Cm7", "Am7", etc.
Diminished: "Cdim", "Bdim", etc.
Augmented: "Caug", "Faug", etc.
Suspended 4th: "Csus4", "Gsus4", etc.
Suspended 2nd: "Csus2", "Dsus2", etc.

Supported Scales

The system supports the following scale types:

Major: "C major", "G major", etc.
Minor: "A minor", "E minor", etc.
Harmonic Minor: "A harmonicminor", etc.
Melodic Minor: "D melodicminor", etc.
Dorian: "D dorian", etc.
Phrygian: "E phrygian", etc.
Lydian: "F lydian", etc.
Mixolydian: "G mixolydian", etc.
Locrian: "B locrian", etc.
Pentatonic Major: "C pentatonicmajor", etc.
Pentatonic Minor: "A pentatonicminor", etc.
Blues: "E blues", etc.

Advanced Usage

Custom Commands

You can extend the system with custom commands by:

Adding new functions to the MCP server (server.py)
Adding corresponding handlers in the FL Studio controller script (device_flstudiocontroller.py)
Implementing the SysEx parsing/handling for complex commands

Creating Complex Musical Progressions

# Create a verse-chorus arrangement
# Verse: Am-F-C-G
# Chorus: C-G-Am-F
verse = ["Am", "F", "C", "G"]
chorus = ["C", "G", "Am", "F"]

# Create verse
create_chord_progression(verse, duration_beats=4, channel=0)

# Create chorus
select_pattern(1)  # Move to next pattern (✅ Working)
create_chord_progression(chorus, duration_beats=4, channel=0)

# Set arrangement (Note: set_arrangement is currently non-functional)
# set_arrangement([0, 0, 1, 1, 0, 1, 1, 1], loop_start=0, loop_end=8)

Generating Lead Melodies Over Chord Progressions