Skip to content

Getting started

The integration has two local pieces: an Ableton Remote Script listening inside Live and a Python MCP server used by your assistant.

1. Install the Remote Script

Copy the repository's BetterAbletonMCP_Remote_Script folder into your Ableton User Library's Remote Scripts folder. On Windows this is commonly:

%USERPROFILE%\Documents\Ableton\User Library\Remote Scripts\

Restart Live. In Preferences → Link, Tempo & MIDI, select BetterAbletonMCP_Remote_Script as a Control Surface. Leave its Input and Output set to None.

2. Install the MCP server

From the repository root:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Optional: selected-audio chord generation

The generate_chords_for_selected_audio tool uses local pitch-analysis libraries that are not installed by the base package. Install the audio extra if you want to turn a selected vocal or other monophonic audio phrase into a chord progression:

pip install -e ".[audio]"

pip install -e ".[audio]"

This installs librosa and soundfile. Audio analysis happens in the MCP server process and does not create an intermediate MIDI transcription. The generated accompaniment is a normal MIDI chord clip. When optional THIRI voicing is enabled, only the locally chosen chord symbols and inferred key are sent; audio is never uploaded.

Optional: THIRI theory and voicing

The base server, local MIDI analysis, and selected-audio workflow do not require an account or API key. To use hosted chord-theory enrichment, reharmonization, or advanced voicings, obtain a key from THIRI Innovate and expose it to the MCP server process:

THIRI_API_KEY=your_rotated_key

Use .env.example as a reference, but configure the variable in your shell or MCP client; the server does not automatically load .env. Keep credentials out of source control. If a key has been pasted into chat, logs, or a commit, rotate it before use.

The official REST endpoint is https://chords.thiri.ai. These optional variables control the client:

Variable Default Purpose
THIRI_API_KEY unset Bearer credential for hosted THIRI requests.
THIRI_API_URL https://chords.thiri.ai API base URL. Remote URLs must use HTTPS; plain HTTP is accepted only for localhost, 127.0.0.1, or ::1.
THIRI_TIMEOUT_SECONDS 8 Positive request timeout in seconds.

For example, an MCP client configuration can add an env object:

{
  "mcpServers": {
    "better-ableton": {
      "command": "C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["-m", "better_ableton_mcp.server"],
      "cwd": "C:\\absolute\\path\\to\\better-ableton-mcp",
      "env": {
        "THIRI_API_KEY": "your_rotated_key"
      }
    }
  }
}

3. Add it to an MCP client

Use absolute paths. A typical configuration is:

{
  "mcpServers": {
    "better-ableton": {
      "command": "C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["-m", "better_ableton_mcp.server"],
      "cwd": "C:\\absolute\\path\\to\\better-ableton-mcp"
    }
  }
}

On macOS or Linux, point command to .venv/bin/python and use the appropriate absolute cwd.

4. Verify the connection

Open a Live set, ensure the Control Surface is enabled, restart the MCP client, and ask:

Get the current Ableton session information.

Track and clip indices are zero-based at the protocol level. Ask for session information first whenever the intended track or slot is ambiguous.

To verify optional audio analysis, click a warped monophonic audio clip in Arrangement View so it appears in Clip View, and ask:

Make a chord progression that goes with the selected vocal clip.

The selected track and the clip shown in Detail/Clip View must refer to the same Arrangement audio clip. The defaults (selection_mode="clip", bars=0) analyze the whole clip and make the generated MIDI clip follow its exact duration; the final chord is shortened when the clip ends partway through a bar. To analyze only a phrase, select it, press Cmd-L/Ctrl-L, and call the tool with selection_mode="loop".

Connection settings

The Remote Script listens on TCP port 9877 by default. The MCP server connects to localhost. Override the client side when needed:

Variable Default Purpose
ABLETON_HOST localhost Host running Ableton Live
ABLETON_PORT 9877 Remote Script socket port

Troubleshooting

  • Could not connect: Confirm Live is running and the Control Surface is selected, then restart the MCP client.
  • Browser unavailable: Wait for Live to finish loading its Browser and retry.
  • Audio clip import fails: create_audio_clip requires Live 12.0.5+, an audio track, an empty Session slot, and an absolute supported-audio path.
  • Harmony analysis or generation reports MidiNote is not subscriptable: Replace the installed BetterAbletonMCP_Remote_Script folder with the current repository version and restart Live. Current releases normalize Live 11/12 MIDI-note objects and support Arrangement-only MIDI sources.
  • Audio-analysis dependencies are missing: Activate the same virtual environment used by the MCP client, run pip install -e ".[audio]", and restart the client.
  • Select an Arrangement audio clip: Click the clip and make sure it is visible in Clip View. Session audio clips are not accepted by generate_chords_for_selected_audio.
  • Arrangement Loop is off or does not overlap: This applies only to the opt-in selection_mode="loop"; select the phrase, press Cmd-L/Ctrl-L, and confirm Live's Loop switch is enabled.
  • Warp or Re-Pitch error: Enable Warp and choose a mode other than Re-Pitch. The analyzer requires at least two warp markers to map source-audio time to Arrangement beats.
  • Audio file unavailable or unreadable: Ableton and the MCP server must expose the clip's source path through the same filesystem. WAV, FLAC, and OGG are dependable choices on typical installs; exact codec support comes from the installed librosa/soundfile stack. Convert to WAV if a compressed format fails.
  • Selection exceeds the analysis limit: Shorten the loop or clip selection to at most 300 seconds of mapped source audio.
  • No reliable vocal pitches: Choose a clearer monophonic phrase or lower minimum_pitch_confidence from its default of 0.65. Polyphonic vocals, dense backing tracks, reverb, and heavy noise can confuse the pitch detector.
  • THIRI_API_KEY is not configured: Set the key in the environment used to launch the MCP server, then restart the MCP client. Alternatively use theory_provider="local"; auto also works locally when no key is present.
  • THIRI is unavailable, timed out, or over quota: theory_provider="auto" returns the local result with a provider_warning. An explicit theory_provider="thiri" request fails instead of silently changing the requested behavior. reharmonize_chord_progression always requires THIRI.
  • THIRI timeout or URL configuration error: THIRI_TIMEOUT_SECONDS must be numeric and positive. THIRI_API_URL must use HTTPS unless it targets a loopback host.
  • Wrong track changed: Inspect the session first; MCP tool indices start at zero.

Ableton version notes

The project supports Ableton Live 11 and 12. Selected-audio analysis uses the Arrangement clip, Detail View, Warp marker, and loop APIs available in those versions. When Live exposes direct Arrangement MIDI-clip creation, the Remote Script uses it; otherwise it copies through an empty Session slot. The separate create_audio_clip import tool still requires Live 12.0.5 or newer. The THIRI integration changes only the Python MCP server; it does not require a new Remote Script command or a different Ableton Live version.