Ableton MCP Server

ableton-mcp-server

:globe_with_meridians: Live Landing Page & Interactive 97-Tool Catalog · Architecture Diagram · Agent Playbook · Tool Index

An open Model Context Protocol (MCP) server that enables AI agents (Antigravity, Gemini, Codex) and audio developers to query, analyze, drive, and automate a running Ableton Live 12 Set.

The current tool surface is 97 tools over TCP, WebSockets, composed routes, and local execution (with primary device resolution via device_name, track_index, and clip_index); the current v0.8.1 release ships 97 tools. Historical milestones exposed 65 certified tools in v0.5.2 , 88 tools in the v0.5.6 source milestone , 96 tools in the v0.6.0 release , and v0.7.0 with journey planning and realtime UDP. v0.8.0 modularizes the Remote Script into 17 domain modules, adds chain-order-safe device insertion (load_device_to_track), and introduces preflight clean-set verification. v0.8.1 removes the curated groove corpus from every distributed package. Groove retrieval, evidence, generation, and comparison stay offline; only the guarded apply path reaches Live. A FastMCP server in Python communicates with a MIDI Remote Script on TCP 127.0.0.1:9888 and an Extension Host bridge over WebSockets on 127.0.0.1:9889.

Groove Intelligence is offline by default. Its deterministic generator needs no provider installation; an optional neural provider is isolated behind a fixed allowlist, bounded local IPC, resource limits, and signed laboratory gates. Provider failures always return the equivalent deterministic artifact, and no provider receives corpus paths, raw MIDI, notes, SQL, credentials, or network access. See the provider laboratory contract. The curated corpus no longer ships inside the wheel or any other distributed package. An optional private seed is read from %LOCALAPPDATA%\AbletonMCPServer\groove-seed (on macOS from ~/Library/Application Support/AbletonMCPServer/groove-seed), or from the path given in ABLETON_GROOVE_SEED_BUNDLE, while derived artifacts stay in the same per-user folder. Groove retrieval, evidence, comparison, and deterministic generation are portable and do not depend on the private source library. A generation request can use one primary groove plus up to seven references; incompatible PPQ, meter, or rights are rejected explicitly. Within the Groove Intelligence surface, the only Live mutation is guarded groove_apply, which must be previewed against an explicit target and empty slot before one commit.

---

⚡ What is Model Context Protocol (MCP) & How Agents Use It

Model Context Protocol (MCP) is an open standard for secure, local communication between Large Language Models (LLMs) and desktop applications.

Local IPC / stdio (Not a Cloud Service):

ableton-mcp-server runs locally on your host OS over standard input/output (stdio) or IPC loopback. The AI agent spawns the ableton-mcp-server.exe process directly. There are no external cloud endpoints or API keys required, guaranteeing zero network latency and maximum privacy.

How AI Agents Interact with Ableton Live:

1. Tool Discovery (`tools/list`): When an MCP client (Antigravity, Cursor, Windsurf) launches the server, it automatically discovers all 97 tool schemas .
2. Tool Execution (`tools/call`): When the LLM decides to manipulate Ableton Live, it issues JSON-RPC messages (e.g. set_tempo(tempo=128.0) or create_clip(...)).
3. Write-Then-Verify Loop: The server writes to Live's local socket and verifies object model state before returning a result.
4. Self-Correcting Error Taxonomy: If an error occurs, the server returns structured codes (CAPABILITY_UNAVAILABLE, AMBIGUOUS_MATCH, VERIFICATION_FAILED), enabling the agent to reason and adapt.

Recommended System Prompt for AI Agents:

You have direct access to an active Ableton Live Set via ableton-mcp-server (97 tools) <!-- TOOL_COUNT: active_total -->.

1. Always start by inspecting the project state using get_session_overview() or get_track_list().
2. To modify track properties, resolve the target track index using live_find_track(name_pattern) first.
3. For parameter adjustments, query parameters via get_device_list() and get_parameter_value(), then apply changes using set_parameter_value().
4. When executing multiple operations, bundle them using run_batch(commands); a successful prefix persists if a later command fails. Live closes an undo step at the end of every UI tick, so Arrangement edits and other commands that finish in one tick share a Ctrl+Z, while each command read back on a later tick (tempo, loop, colours, cue points) takes its own.
5. Respect the error taxonomy: if you receive AMBIGUOUS_MATCH or VERIFICATION_FAILED, inspect track context and retry.

---

🛠️ Use It

License is MIT. Copy, fork, ship — see LICENSE.

Windows Install (one-shot):

powershell -ExecutionPolicy Bypass -File .\scripts\setup_windows.ps1

Install the release wheel from the project's GitHub Releases page (the downloaded .whl file). There is no PyPI install for this server: the public ableton-mcp-server name on PyPI belongs to an unrelated project.

Preview the exact Remote Script copy plan without creating .venv-win, installing dependencies, or writing to Ableton's User Library:

powershell -ExecutionPolicy Bypass -File .\scripts\setup_windows.ps1 -DryRun

If the environment already exists, the equivalent CLI preview is:

.\.venv-win\Scripts\ableton-mcp.exe install-script --dry-run

Then restart Live, select AbletonMCPServer under Preferences -> Link, Tempo & MIDI -> Control Surfaces, and verify the installation:

.\.venv-win\Scripts\ableton-mcp.exe doctor --json

Verify Install

You can verify your installation integrity using either the built-in CLI tool or direct SHA-256 hash comparison:

1. CLI Remote Script Status

Run install-status to compare installed Remote Script files against the bundled source:

.\.venv-win\Scripts\ableton-mcp.exe install-status --json

A healthy, up-to-date installation returns "status": "current":

{

"status": "current", "source": "C:\\path\\to\\ableton-mcp-server\\AbletonMCPServer_RemoteScript", "target": "C:\\Users\\ \\Documents\\Ableton\\User Library\\Remote Scripts\\AbletonMCPServer_RemoteScript", "missing_files": [], "mismatched_files": [] }

2. SHA-256 Checksum Audit

During setup, setup_windows.ps1 automatically verifies and prints the Remote Script's SHA-256 hash:

Remote Script verification:

algorithm: SHA256 hash: 3E3504D661FA2DCE7582F50C56F0C71EB79892F7A4520BD3F1B8571EEDBB14DE path: C:\Users\ \Documents\Ableton\User Library\Remote Scripts\AbletonMCPServer_RemoteScript\init.py

To manually compute and verify the SHA-256 checksum of the installed __init__.py at any time:

• Windows (PowerShell):

  Get-FileHash "$HOME\Documents\Ableton\User Library\Remote Scripts\AbletonMCPServer_RemoteScript\__init__.py" -Algorithm SHA256

• macOS / Linux:

  shasum -a 256 "$HOME/Music/Ableton/User Library/Remote Scripts/AbletonMCPServer_RemoteScript/__init__.py"

The Remote Script spans several modules, so ableton-mcp install-status --json is the check that compares every installed file.

Agent Configuration (mcp.json):

{

"mcpServers": { "ableton": { "command": "C:\\path\\to\\ableton-mcp-server\\.venv-win\\Scripts\\ableton-mcp-server.exe", "args": [] } } }

If you operate from WSL2, point the MCP client at the Windows binary so loopback stays in the host network namespace:

/path/to/ableton-mcp-server/.venv-win/Scripts/ableton-mcp-server.exe

MCP Bundle (.mcpb)

scripts/build_mcpb.py packs the server as an MCP Bundle for Windows. The bundle carries the wheel and a locked launcher project; on first launch the host's uv installs Python and the dependencies from PyPI. It contains the server only, so the Remote Script and the Extension still install as described above.

.\.venv-win\Scripts\python.exe scripts\build_mcpb.py build --out-dir dist\mcpb

.\.venv-win\Scripts\python.exe scripts\build_mcpb.py smoke dist\mcpb\ableton-mcp-server- .mcpb

build needs uv, Node.js (npx runs the pinned @anthropic-ai/mcpb CLI), and network access. smoke extracts the bundle, launches it over stdio, and checks initialize, tools/list against the catalog, and one offline tool, without Ableton Live.

Optional private groove seed

The curated groove corpus is not part of this wheel, the MCP bundle, or any other distributed package. No groove corpus is downloaded at install time or later. The server starts normally and exposes all 97 tools without a corpus; only the corpus-backed operations need one.

When you have a licensed local copy, point the server at it with either:

• %LOCALAPPDATA%\AbletonMCPServer\groove-seed — the default location on Windows.
• ~/Library/Application Support/AbletonMCPServer/groove-seed — the default location on macOS.
• ABLETON_GROOVE_SEED_BUNDLE — an explicit path that overrides the default location.

Without a configured seed the corpus operations (groove_search, groove_evidence, groove_compare, and groove_generate from a corpus source) answer with an explicit error instead of fetching anything. The two messages are literal:

No groove corpus configured: no seed bundle at <bundle>. Set ABLETON_GROOVE_SEED_BUNDLE, or place a licensed seed there.

Invalid groove seed at : . Set ABLETON_GROOVE_SEED_BUNDLE to a valid seed bundle.

---

📦 What It Does (97 MCP Tools)

v0.6.0 extends the certified 65-tool v0.5.2 baseline . v0.5.3 introduced colour writes, clip-target diagnostics, and five hierarchy tools that validate then return CAPABILITY_UNAVAILABLE; v0.6.0 adds offline music generation, Groove retrieval, and guarded apply. See the offline music reference.

The 97 MCP tools are grouped into operational domains :

• Transport & Session: get_session_info, set_tempo, start_playback, stop_playback, get_loop_settings, set_loop, set_loop_start, set_loop_length, set_current_song_time, get_song_length, get_session_overview, get_scenes, get_scene_state, fire_scene, fire_clip.
• Tracks & Devices: get_track_list, live_find_track, live_find_device, live_find_clip, get_track_state, get_device_list, list_device_params, get_parameter_value, get_plugin_presets, set_plugin_preset, get_clip_summary, set_parameter_value, create_clip, get_clip_notes, add_notes_to_clip, delete_clip, clear_clip_notes, set_clip_properties, get_clip_info, set_track_property, set_track_color, set_clip_color, diagnose_clip_targets, create_midi_track, create_audio_track, rename_track, move_track, reorder_tracks, move_track_to_group, ungroup_track, merge_groups, get_routing, diff_snapshots_tool, take_snapshot, get_selected_context, get_composition_structure, diagnose_midi_clip, search_browser, load_device_to_track, get_warp_state, set_warp_state.
• Lifecycle & Automation: lifecycle_status, `sa