ableton-mcp-server

🌐 Live Landing Page & Interactive 96-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 96 tools over TCP, WebSockets, composed routes, and local execution (with primary device resolution via device_name, track_index, and clip_index); the current v0.6.0 release ships 96 tools. Historical milestones exposed 65 certified tools in v0.5.2 and 88 tools in the v0.5.6 source milestone . v0.6.0 adds three deterministic offline music-generation tools and five Groove Intelligence tools. 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 seed ships inside the wheel; ABLETON_GROOVE_SEED_BUNDLE can override it explicitly, while derived artifacts stay in LocalAppData. 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 96 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 (96 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)` for one grouped undo step; a successful prefix persists if a later command fails.
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

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\\<user>\\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\<user>\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"

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

---

📦 What It Does (96 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 96 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, save_set, quit_ableton, live_fade, create_clip_automation.
• Offline Mix Analysis: analyze_audio, find_frequency_masking, analyze_mix, extract_single_cycle (LUFS-I, True Peak, dynamic range, spectral collision).
• Groove Intelligence (offline by default): groove_search, groove_evidence, groove_generate, groove_compare, groove_apply (genre/subgenre/style/section taxonomy, V2 projections, deterministic multi-parent generation, late kit mapping, and one guarded Live commit).
• Inspection & Batch Execution: run_batch, get_locators, create_cue_point, delete_cue_point, bulk_create_cue_points, get_control_surfaces, get_browser_categories, get_project_metadata, get_ableton_logs, get_bridge_status.

Offline Music Generation

Inventory	Tools	Live boundary
Deterministic music generation	music_generate_drum_groove, music_generate_bass, music_plan_production	Offline by default; only an explicit apply request reaches Live.

---

💡 Inspiration & Prior Art

This project builds on design insights from seminal open-source projects:

• pnomolos/live-wire — TCP JSONL Remote Script layout, typed error envelopes, per-tick verification loop.
• hidingwill/AbletonBridge — run_batch transaction semantics and attribute verification.
• ideoforms/AbletonOSC — OSC command naming and Extension Host bridge conventions.
• ideoforms/pylive — Python LOM introspection reference.
• Simon-Kansara/ableton-live-mcp-server — Tool boundary design (Remote Script for transport/devices vs WebSocket Extension for warping/browser loading).

Full notes in docs/INSPIRATION.md.

---

⚠️ Known Bugs

Live's Object Model exposes a number of traps (path-id drift, undo semantics, WSL loopback, protocol drift, allowlist surprises) that an AI agent can hit without warning. Each one has a known workaround in the codebase; every trap is documented in docs/KNOWN_BUGS.md. Read the executive summary at the top of that file before relying on track indexes, run_batch, or a TCP loopback to Live.

---

📜 License

MIT — Copyright (c) 2026 Gabriel Worm (ntworm). See LICENSE.