ableton-mcp

MCP server that lets an MCP client (Claude Code) drive Ableton Live 12.1+ (Lite included) through a stdlib-only Remote Script. It also builds and reads presets for the free Vital synth, and has an offline .mid writer. Both work with Live closed.

Tested on Live 12.1.10 Lite (embedded Python 3.11.6) and Vital 1.5.5, macOS. Session View only.

How it works

• remote_script/AbletonMCP/: Live loads this as a Control Surface. It listens on 127.0.0.1 on a random port. It writes {port, token} to ~/.ableton-mcp/connection.json (mode 0600) and removes the file when Live quits. On each Live timer tick (~100 ms) it handles up to 64 pending JSON-lines requests on Live's main thread. Each change is one undo step. A request that arrives after its deadline is refused, so a timed-out write never lands late.

• src/ableton_mcp/: the MCP server (stdio). It reads connection.json on every call and never retries a request.

• src/ableton_mcp/vital.py: Vital has no remote control, so the Vital tools write .vital preset files (plain JSON) to ~/Music/Vital/User/Presets/, where Vital's browser finds them. If the Vital app is closed, the tool starts it with the new preset. Inside Live, load Vital on a track and pick the preset in its browser. Format notes: docs/vital-mcp-research.md.

Related MCP server: ableton-live-mcp

Install

Requires uv and Live 12.1 or newer.

uv sync
uv run ableton-mcp install-script          # copies the script to ~/Music/Ableton/User Library/Remote Scripts/AbletonMCP
# other User Library location: uv run ableton-mcp install-script --user-library "/path/to/User Library"

Restart Live. Open Settings → Link, Tempo & MIDI, and pick AbletonMCP in a Control Surface slot (leave Input/Output as None). Log.txt (~/Library/Preferences/Ableton/Live 12.x.y/Log.txt) should then show AbletonMCP listening on 127.0.0.1:<port> (Python 3.11.x).

Re-run install-script and restart Live after every change to remote_script/.

Register with Claude Code:

claude mcp add ableton -- uv --directory /path/to/ableton-mcp run ableton-mcp

Check the whole setup:

uv run ableton-mcp doctor    # add --user-library "/path/to/User Library" if you installed elsewhere

It checks the Live app version, Live's Log.txt, the installed script against the repo, connection.json, a read-only hello to Live, and the Claude Code registration (claude mcp get ableton). Each line is PASS, WARN, FAIL or SKIP, and each FAIL or WARN prints its fix. Exit code 1 means at least one FAIL.

Check the bridge without an MCP client:

uv run ableton-mcp call hello
uv run ableton-mcp call browse '{"root":"drums","path":[]}'

Tools

uv run ableton-mcp runs the stdio server with 29 tools, in this order:

If Live or the Remote Script is not reachable, or the script reports an error, the tool returns an isError result with the reason.

Tools that delete tracks or clips, replace a clip's notes, or write a generated clip (create_drum_pattern, create_bassline, create_chord_progression replace any clip in the target slot) carry destructive_hint: true, so the client can ask before it runs them. Every other write tool carries destructive_hint: false.

Lessons and resources

The server also sends instructions to the agent once per session (src/ableton_mcp/lessons.py). They tell it to check Live before changing anything, explain each change in plain words, reuse tracks under Lite's limits, offer undo_last, and remind you once to press Cmd+S at the end of a task that changed the Set.

Guided lessons are MCP prompts. In Claude Code, type / and pick one. They take no arguments: the lesson asks you instead.

The lessons follow the chapter order of Ableton's Learning Music and link each chapter for hands-on practice. The site states no licence, so the lesson texts are our own words and only link to it.

Two read-only resources return the same JSON as their tools. Attach one to a message with @:

• @ableton:live://capabilities: same as live_status.

• @ableton:live://set/overview: same as get_set_overview.

The ableton: prefix is the name the server was registered under (claude mcp add ableton ... in Install). Under another name, the commands and mentions use that name instead.

Limits

• Live Lite allows 8 audio+MIDI tracks. create_midi_track checks this before it calls Live; free a track with delete_track or reuse one.

• Live Lite allows 16 scenes. create_scene checks this before it calls Live; name and reuse empty scenes with set_label.

• Live Lite allows 2 return tracks (A and B). Return and master track mixing is not supported; set_track_mix covers audio, MIDI and group tracks.

• Volume and send levels are in dB. In get_set_overview, null means -inf (silent). set_track_mix takes numbers only; to silence a track, use mute.

• Solo is not exclusive: set_track_mix(solo=true) does not unsolo other tracks. Unsolo them yourself.

• Colours are 10 names (red, orange, yellow, lime, green, cyan, blue, purple, pink, grey). Live snaps each to the nearest colour in its chooser.

• live_status compares the Remote Script's protocol version with the server's. After an upgrade, run install-script again and restart Live.

• read_notes does not return mute or probability, so a read_notes + write_notes round trip resets them. Notes that start at or after the clip length never play; write_notes reports them as notes_outside_clip.

• drum_pads comes from the first Drum Rack on the track: top level first, then one level inside other racks (many Lite kits wrap their Drum Rack in an Instrument Rack). Deeper nesting is not searched.

• The LOM cannot save the Set. Press Cmd+S yourself.

• Devices load only through the browser (load_from_library, load_instrument), so a load replaces the current instrument and is one undo step. Track.insert_device (Live 12.3) is not used; live_status reports it under features.

• load_instrument kinds: drift, simpler, impulse, drum_rack, drum_sampler and instrument_rack are in every edition. operator, wavetable, analog and meld (use drift) and sampler (use simpler) are refused on Lite before Live is called. On Standard/Suite they load by browser name; that path is untested.

• load_instrument presets: it searches the kind's browser folder and each folder one level below it (drum_rack: the drums root), one browse call per folder (14 for Drift on Lite). The first name match in browser order wins; the result returns the loaded path. Other presets: browse_library + load_from_library.

• Device parameters are raw values between min and max, not units. Read display (Live's own text) after a set and adjust. display_value (Live 12.2+) is not used. A parameter with enabled: false is controlled by a macro or locked; set_device_parameters refuses it.

• Some Core Library rack presets (e.g. "Basic Analog Bass", "808 Drifter") hide their chains: Live shows only the macros and the LOM reports chains: []. Use the macros. Racks with visible chains (e.g. "Ahlimba Kit") can be read inside with device_path [0, chain, device].

• A .mid from write_midi_file holds notes only. Drop it on a track with an instrument, or it plays silent. It never overwrites an existing file; reuse of a name returns an error.

• Vital presets are files: Vital has no remote control, so the agent cannot tweak a sound live or hear it. vital_create_preset opens the Vital standalone with the preset only when Vital is closed (a second launch would start a second instance). If Vital is open, or runs inside Live, pick the preset in Vital's preset browser under User. Vital's --render crashes on 1.5.5, so there is no offline preview. Presets never overwrite an existing file. Waves are saw, square, triangle and sine only. The sample source plays silence or 1 s of white noise (a loop you may hear as a repeat on long notes); no audio files. 94 common controls are accepted, including the comb and formant filter controls, and unknown names are refused.

• load_from_library with an instrument replaces the track's current instrument. undo_last restores it.

• Generators are 4/4 only and refuse a Set in another signature. Their .mid files are always 4/4 at 120 BPM.

• Scales: Major, Minor, Dorian, Phrygian, Lydian, Mixolydian, Locrian, Harmonic Minor, Melodic Minor, Major Pentatonic, Minor Pentatonic, Minor Blues. Any other name is refused before Live is called. create_chord_progression needs a 7-note scale.

• create_drum_pattern picks each voice's pad by a keyword in the pad name first (e.g. "Kick", "Snare", "Hihat Closed"), then by its General MIDI note (36 kick, 38 snare, 42 closed hat, 46 open hat, ...) if no other voice claims that pad by name. Kits with odd or empty pad names can leave voices unresolved; the result lists them in missing_voices.

• Generators replace the clip in the target slot as one undo step. They never create tracks or load instruments. Melodic clips need an instrument on the track, or they play silent.

• If Live shows a modal dialog, calls time out. A timed-out change may still have run: check get_set_overview before retrying.

Manual smoke checklist (real Live)

1. Upgrade only: with the old script still installed, live_status returns the install-script hint.

2. install-script, restart Live, select AbletonMCP. Log.txt shows AbletonMCP listening and Python 3.11. doctor prints no FAIL and exits 0.

3. call hello shows your Live version, edition (variant) and protocol_version: 5.

4. call browse '{"root":"drums","path":[]}' lists the drum kits.

5. In Claude Code, ask "make a 1-bar 4/4 drum beat on a new track and play it". You get a new track, a kit, a clip with notes, and sound. Cmd+S still saves.

6. undo_last removes only the last tool's change.

7. Lite only: with 8 tracks, asking for another returns the edition-limit error and Live shows no dialog. In Claude Code, "add a bass track" makes the agent delete or reuse a track.

8. call get_overview shows drum_pads names (e.g. "Kick", "Snare") for a kit track. call get_notes '{"track":N,"slot":0}' lists the drum clip's notes.

9. call delete_track '{"track":N}' removes the track; one call undo restores it with its clip and kit.

10. Quit Live. get_set_overview returns the Control Surface hint, and write_midi_file still writes a .mid that you can drag into Live.

11. A uv run python -c loop calls LiveClient().call("set_scale", ...) for each of the 12 scales and prints any whose returned intervals differ from theory.SCALES. It prints nothing; the MIDI editor highlights the last scale.

12. On an 808 Core Kit track, create_drum_pattern(style="house", bars=2, track=0, slot=1) returns no missing_voices and plays as house. One undo_last removes the clip. On an occupied slot, one undo_last restores the old clip and its notes.

13. Load a Lite kit with empty pad names (e.g. "Ahlimba Kit"). create_drum_pattern(style="rock") resolves kick, snare and closed_hat.

14. In a fresh Claude Code session, "make a hip hop beat, a bassline and chords in A minor" calls set_scale, create_drum_pattern, create_bassline and create_chord_progression (no write_notes). All three clips play in key.

15. With Live closed, "write me a house beat as a MIDI file" writes a .mid in ~/Music/ableton-mcp/midi/ that plays on a kit when dragged in.

16. call get_overview (read-only) shows mix.volume_db 0.0 and pan 0 for a default track, return_tracks A/B with their names, and 8 scenes. A dB parse error shows here, before any setter runs.

17. set_track_mix(track=0, volume_db=-6, pan=25, sends={"A": -12}): Live shows -6.0 dB, 25R and send A at -12 dB. One undo_last restores all three.

18. create_scene(copy_of=0) adds a copy below scene 0 with the same clips. fire_scene(scene=1) plays that row.

19. set_label with color="red" on a track, a clip and a scene shows red in Live. copy_clip into an empty slot plays. Cmd+S still saves.

20. Lite only: with 16 scenes, create_scene returns the Lite error and Live shows no dialog.

21. In Claude Code, "turn my loop into a song with intro, verse and chorus" names the scenes, copies or varies the clips, colours them by role and fires the scenes in order.

22. call get_device '{"track":1,"device_path":[0]}' on a rack preset (e.g. "Basic Analog Bass") lists its macro parameters and chains: [] (its chains are hidden). On "Ahlimba Kit", [0,0,0] reaches the Drum Rack and [0,0,1] the Saturator. No display is blank.

23. In Claude Code, "put a Drift on track 5" calls load_instrument(4, "drift") and track 5 shows Drift. "load the Deep Bass preset on track 6" loads it with one load_instrument call and no browse_library.

24. set_device_parameters on two Drift parameters: the returned display matches Live's UI. One undo_last restores both.

25. Lite only: "use Operator for the lead" gets the refusal, and the agent loads Drift instead.

26. uv run python -c "import asyncio; from ableton_mcp import server; print(asyncio.run(server.mcp.read_resource('live://capabilities')))" shows your Live version, edition and limits ("audio_midi_tracks": 8 on Lite).

27. In Claude Code, after /mcp reconnect: typing /lesson lists the six /ableton:lesson-* commands, /ableton:explain-my-set is there, and typing @ableton: offers both live:// resources.

28. /ableton:lesson-first-beat builds a playing beat step by step, explains the drum roles and tempo, links the Beats chapter, and ends with one Cmd+S reminder and the next lesson's command. /ableton:explain-my-set makes no write tool call.

29. In a fresh session with no lesson, "add an open hi-hat on the off-beats" gets a plain-words summary of the change and one save reminder at the end, not one after each tool call.

30. With the Vital app closed, ask Claude Code for "a warm detuned supersaw pad". Vital opens with the new preset, and its values match the tool call. With Vital open, the same request starts no second instance, and the preset is in the browser under User. In Live, Vital loaded with load_from_library plays the preset with notes from create_chord_progression.

31. With the Vital app closed, ask for "a plucked string from a noise burst". The sample panel shows White Noise on, filter 1 shows a comb style, and C3 and C4 ring at different pitches and decay like a pluck. Then ask for "a vowel 'ah' to 'ee' formant pad": filter 1 shows Formant with AOIE or AIUO, and moving the vowel pad in Vital changes the vowel from where the tool set it.

Development

uv sync
uv run pytest -q

CI (.github/workflows/test.yml) runs the suite on Python 3.11 (Live's embedded version) and 3.13 for every push to main and every pull request. Keep src/ and remote_script/ working on 3.11.

License

MIT, see LICENSE. Some design patterns come from other MIT-licensed Live projects. They were re-implemented here, and no code was copied.