# ableton-mcp

An MCP server to control Ableton Live via the Live API.

Live's API is only reachable from Python running inside Live, so this is two
processes talking over TCP on localhost:

- `remote_script/AbletonMCP` runs inside Live as a control surface. It polls a
  non-blocking socket from Live's main thread on a 100ms tick, so every
  command runs on the main thread and no threading hacks are needed.
- `server/` is the MCP server (TypeScript, Node). It translates tool calls
  into bridge commands over a length-prefixed JSON protocol.

## What it can do

46 tools across two layers.

Curated tools:

- Transport and song: play/stop, tempo, time signature, loop region,
  quantization, undo/redo, cue points
- Tracks: create/delete/duplicate (MIDI, audio, return), name/color/arm/
  mute/solo, monitoring, input/output routing
- Scenes: create/delete/duplicate/fire
- Clips: session and arrangement, create/delete/fire, loop points, markers,
  launch settings, warp/gain/pitch, place session clips on the timeline
- MIDI notes: read, add, update, and remove by stable note ID, so existing
  clips can be edited instead of overwritten
- Mixer: volume, pan, sends, crossfader, with display strings ("0.0 dB")
- Devices: list (including rack chains and drum pads), read parameters, set
  by name or option, delete
- Automation: write/read/clear clip envelopes on any device or mixer
  parameter
- Browser: navigate, search, and load instruments/effects/presets onto a
  track

Generic layer: `live_get`, `live_set`, `live_call`, and `live_describe` reach
the entire Live Object Model through paths like
`song.tracks[0].devices[0].parameters[3]`, covering anything the curated
tools don't.

Plus a change-event feed (subscribe to any listenable Live property, poll
by cursor) and self-setup tools that install the remote script for you.

## Setup

### Claude Desktop (no tools required)

1. Download `ableton-mcp.mcpb` from the
   [latest release](https://github.com/brantstuns/ableton-mcp/releases) and
   open it — Claude Desktop installs it like a browser extension. One file
   for every platform; no Python, Node, or uv install needed.
2. Ask Claude to set up Ableton: it installs the remote script itself via
   the `install_remote_script` tool.
3. Restart Live and enable AbletonMCP under
   Settings > Link, Tempo & MIDI > Control Surface.

### From a checkout

Requires Live 11 or newer and Node 18+.

1. Build the server:

```sh
cd server && npm install && npm run build
```

2. Install the remote script (`--symlink` if you're hacking on it):

```sh
python3 scripts/install_remote_script.py
```

3. Restart Live, then pick AbletonMCP as a control surface under
   Settings > Link, Tempo & MIDI.
4. Register the server with your MCP client, using the absolute path to
   this cloned repo:

```json
{
  "mcpServers": {
    "ableton-live": {
      "command": "node",
      "args": ["/Users/you/dev/ableton-mcp/server/dist/index.js"]
    }
  }
}
```

## Development

Two halves, two test suites:

```sh
# remote script (python, runs against a fake Live object model)
uv sync && uv run pytest

# MCP server (typescript)
cd server && npm install && npm test && npx tsc --noEmit
```

Neither suite needs Live running. CI runs both on every pull request.

With Live open and the control surface enabled, the integration suite does
real round trips (creates and deletes a scratch track):

```sh
ABLETON_MCP_LIVE_TESTS=1 uv run pytest tests/integration -v
```

Releases are tagged from main; see CHANGELOG.md.