ableton-mcp-pro

A fork of ahujasid/ableton-mcp — the Model Context Protocol bridge between Claude (and other MCP clients) and Ableton Live. This fork adds 28 additional tools and an audio-listening loop that lets the LLM analyze Ableton's master output and make empirical mixing decisions.

44 tools total (16 upstream + 17 Phase 1 + 10 Phase 2 + 1 Phase B). Runs side-by-side with upstream on port 9878.

What's new vs. upstream

Phase 1 — Sound design, mixing, scenes, MIDI editing (17 tools)

Effects + device parameters: insert_native_device (load any Ableton native device by name — Reverb, EQ Eight, Saturator, etc.), get_device_parameters / set_device_parameter (read and write any knob on any device), delete_device
Mixer: set_track_volume, set_track_pan, set_track_send, set_track_mute_solo_arm
Tracks: create_audio_track, delete_track
Scenes: create_scene, fire_scene
Clip MIDI editing: get_clip_notes, remove_clip_notes (the upstream could only blind-write)
Rack macros: get_rack_macros
Safety: undo, redo

Phase 2 — Browser search, return tracks, drum pads (10 tools)

Browser search: search_browser — find loadable presets by name across all categories (this is also how you load .adv presets, which the upstream couldn't do)
Return tracks: get_return_tracks, get_return_device_parameters, set_return_device_parameter, set_return_track_volume, set_return_track_pan — tune shared sends like the default A-Reverb
Track grouping: group_tracks (graceful fallback — song.group_tracks is not exposed in Live 12.1.1's Python API; tool returns a clean error pointing to manual Cmd-G)
Drum pads: get_drum_pads, set_drum_pad_mute_solo
MIDI capture: capture_midi

Phase B — Audio-listening loop (1 tool)

analyze_master_output(seconds) — captures Ableton's master output via BlackHole, returns structured analysis:

Integrated LUFS (ITU-R BS.1770), peak dBFS, RMS dBFS, crest factor
Clipping check
7-band frequency split (sub / bass / low_mid / mid / upper_mid / presence / air) with per-band energy %
L/R stereo correlation
Spectral centroid (overall brightness)

The LLM can then make claims like "your low_mid is at +6dB and the kick is clipping, drop SUB volume by 2dB and add an EQ Eight low-shelf cut at 250Hz" — empirical decisions instead of guesses.

Prerequisites

macOS (this fork is currently macOS-only — Linux/Windows would need different audio capture + Remote Script paths)
Ableton Live 11+ (tested on Live 12.1.1 Suite)
Python 3.10+
uv — brew install uv
An MCP client like Claude Code
(Optional, for Phase B audio listening): BlackHole 16ch — brew install blackhole-16ch

Installation

git clone https://github.com/Shaydeepalms/ableton-mcp-pro.git
cd ableton-mcp-pro
./setup.sh

The setup script will:

Create a Python venv inside the repo and install dependencies
Deploy the Remote Script to ~/Music/Ableton/User Library/Remote Scripts/AbletonMCPPro/
Print the exact MCP config snippet you need to paste into your client's config

After running the script, three manual steps:

Add the printed config snippet to your MCP client's config — for Claude Code this is ~/.claude.json (global) or a project-local .mcp.json
Restart Ableton Live, go to Settings → Link, Tempo & MIDI, set one of the Control Surface slots to AbletonMCPPro, with both Input and Output set to None
Restart your MCP client so it loads the new server

Once running, you should see mcp__ableton-pro__* tools available in Claude.

Phase B — Audio listening setup (optional but recommended)

If you want Claude to listen to your mix:

Install BlackHole: brew install blackhole-16ch
Open Audio MIDI Setup (macOS Utilities) → create a Multi-Output Device containing both BlackHole 16ch and your physical output (speakers / headphones / audio interface)
In Ableton: Settings → Audio → Output Device → pick that Multi-Output Device (not BlackHole directly — that would route all audio to the virtual driver and you'd hear silence)

Now analyze_master_output(seconds) will capture and analyze whatever's playing in Ableton.

Architecture

Two processes connected via TCP socket on localhost:9878:

Claude (stdio) ⇄ MCP Server (Python / FastMCP) ⇄ TCP:9878 ⇄ Remote Script (inside Ableton)

MCP Server (MCP_Server/server.py) — Python, runs in your MCP client's process. Translates each tool call to a JSON command.
Remote Script (AbletonMCP_Remote_Script/__init__.py) — Python, runs inside Ableton as a MIDI Control Surface. Listens on port 9878, dispatches commands against Live's Python API. State-mutating handlers are scheduled on Ableton's main thread.
Audio analyzer (MCP_Server/audio_analyze.py) — captures audio from BlackHole, runs librosa / pyloudnorm analysis. Independent of the socket — direct audio capture via PortAudio.

The fork uses port 9878 (vs. upstream's 9877), so you can run both side-by-side if you want to keep the upstream Ableton MCP as a fallback.

Live API limits worth knowing

Automation envelopes can't be written programmatically — automation_state is read-only. Workaround: a Max for Live companion device (not yet built).
No audio recording from the API — would need a reverse BlackHole capture, similar to Phase B but in reverse.
No File → Save / Save As — UI-only. AppleScript wrapper would work but is fragile.
song.group_tracks(...) is not exposed in Live 12.1.1's Python API. Our group_tracks tool returns a clean error pointing to manual Cmd-G.
.adv preset loading DOES work via browser URIs — use search_browser to find the URI, then load_instrument_or_effect.

Full handbook

See CLAUDE.md for:

All 44 tools with descriptions
Architecture details (dual-install, port assignments, dev loop)
Decision log (parameter-curve non-linearity, device auto-reordering, etc.)
"How to extend" worked example (adding a new tool end-to-end)
Real-song builds + mixing analysis (Bon Iver-style productions)

Acknowledgments

Built on ahujasid/ableton-mcp by Siddharth Ahuja. Community Discord: https://discord.gg/3ZrMyGKnaU.

License

MIT — see LICENSE. Original copyright Siddharth Ahuja (2025); fork additions copyright Shaydeepalms (2026).

MCP Servers