Skip to main content
Glama
mcp-server-ableton-live

mcp-server-ableton-live

README.md
<!-- mcp-name: io.github.datarat-sound/ableton-mcp--datarat -->

# ableton-mcp--datarat

[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)

An MCP server for driving Ableton Live 11/12 from Claude (or any MCP client),
maintained by **[datarat](https://github.com/datarat-sound)** as a working tool for
writing and producing electronic music: chords, drums, bass design, arrangement and
automation.

A Remote Script runs inside Live and exposes the Live API over a local socket. The
MCP server turns that into 156 typed, validated tools, plus offline tools that read
and diff saved `.als` / `.adg` files with Live closed.

## What's different in this fork

- **`write_automation` draws real shapes.** Each point holds its value until the
  next point, and the last point holds to the clip end. Two points give a flat line
  with one step, dense points (about every 1/16 beat) give a smooth ramp, and a pair
  of points a hair apart gives an instant jump. Upstream drew every point as a
  zero-length spike. *Verified in Live 12.4.*
- **Version tag** `1.8.1+datarat.N`, so `doctor` and `get_session_info`
  (`bridge_version`) show which build is running.

See [CHANGELOG.md](CHANGELOG.md) for details.

## Known limits of the Live API

- **Ramps are staircases.** A script can only write flat steps (`insert_step`); it
  cannot place a single breakpoint that Live slopes into the next one, or delete one.
  For a smooth curve, send dense points. For a perfectly straight line, draw two
  breakpoints by hand.
- **Arrangement clips can't take envelopes from a script.** `duplicate_to_arrangement`
  places the clip, but Live refuses `create_automation_envelope` on Arrangement
  clips, so Session envelopes are not carried over (the tool reports this). To get
  them into the Arrangement, record the Session clip with `record_section`, or draw
  them by hand.
- No render, export or freeze: those stay manual.

## Setup

You need Ableton Live 11 or 12, Python 3.10+, and [uv](https://docs.astral.sh/uv/).

**1. Register the server** (Claude Code):

```bash
claude mcp add AbletonMCP -s user -- uvx --from git+https://github.com/datarat-sound/ableton-mcp--datarat@main-datarat mcp-server-ableton-live
```

Other clients (Claude Desktop, Cursor), in the `mcpServers` block:

```json
{
  "mcpServers": {
    "AbletonMCP": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/datarat-sound/ableton-mcp--datarat@main-datarat",
        "mcp-server-ableton-live"
      ]
    }
  }
}
```

If uv picks a broken Python, pin one with `uvx --python 3.14 ...`.

**2. Install the Remote Script** into your User Library:

```bash
uvx --from git+https://github.com/datarat-sound/ableton-mcp--datarat@main-datarat mcp-server-ableton-live install
```

Add `--user-library "/path/to/User Library"` if your library is not in the default
place (for example on another drive), and `--replace` to overwrite an older script
(a backup is kept). Rerun this after every update so the Live side matches the server.

**3. Turn it on in Live.** Restart Live, open **Settings > Tempo & MIDI** (older
versions: **Link, Tempo & MIDI**), and in an empty **Control Surface** row pick **AbletonMCP** with Input and Output set to
**None**.

**4. Check it.**

```bash
uvx --from git+https://github.com/datarat-sound/ableton-mcp--datarat@main-datarat mcp-server-ableton-live doctor --json
```

Use the same `--user-library` here as for `install`.

## Tools

| Area | Covers |
|---|---|
| Session and transport | session info and snapshot, play/stop, tempo, time signature, loop, locators, scenes, undo/redo, capture MIDI, song scale, groove and swing |
| Tracks and mixer | create/delete MIDI, audio and return tracks, volume, pan, mute, solo, arm, sends, routing, meters, take lanes |
| Clips and notes | create clips, write and edit MIDI notes, quantize, groove, loop, clip automation |
| Devices | browse and load instruments/effects (including Master and Returns), read and set parameters, racks and macros, Simpler, drum pads |
| Arrangement | place, list and delete Arrangement clips, record a section to WAV |
| Generators | drums, Euclidean rhythms, chord progressions and voicings, melodies, basslines, humanize |
| Analysis | key detection, mix scan, session diff, audio file peak/RMS |
| Offline | summarize, extract MIDI, detect key and diff saved `.als`; parse `.adg`/`.adv` racks |
| Batch | many edits in one round trip and one undo step |

Set `ABLETON_TOOLSETS` to load only some groups, for example
`ABLETON_TOOLSETS=session,tracks,clips,devices`. Groups: `session`, `tracks`, `clips`,
`devices`, `browser`, `arrangement`, `generators`, `audio`, `analysis`, `offline`,
`recipes`. Unset loads everything.

## Conventions

- Indices are 0-based. Times and lengths are in beats. Volume uses Live's 0.0–1.0
  fader range, where 0.85 is 0 dB.
- Device parameters use their own native ranges: read `get_device_parameters` first.
- `add_notes_to_clip` replaces all notes; `edit_notes` changes a few.
- `duplicate_to_arrangement` overwrites whatever is under the destination.
- Transport replies report the state *before* the command; confirm with
  `get_session_info`.

## Troubleshooting

- **AbletonMCP missing from Control Surfaces:** the folder must be named exactly
  `AbletonMCP`, and Live only scans at startup, so restart Live.
- **Every command times out:** a dialog is open in Live (on the trial, the startup
  nag). Dismiss it and retry.
- **Port 9877 not listening:** Live isn't running or the Control Surface isn't set.
  If another program uses 9877, set `ABLETON_MCP_PORT` for Live and `ABLETON_PORT` for
  the server.

## Security

The Remote Script listens on `127.0.0.1:9877` with no authentication. Keep it on
loopback and don't forward the port. See [SECURITY.md](SECURITY.md).

## Development

```
ableton_live_mcp/
  server.py        entrypoint: MCP server or a setup subcommand
  app.py           FastMCP app, lifecycle, server instructions
  connection.py    socket client to the Remote Script
  cli.py           install / uninstall / doctor
  tools/           the MCP tools, grouped by area
  remote_script/   the Live-side script and its command dispatch
tests/             protocol, dispatch-contract and registration tests (no Live needed)
```

```bash
uv run --extra dev pytest
uvx ruff check .
```

Remote Script changes only reach Live after `install --replace` and a Live restart.

## Credits and license

Maintained by [datarat](https://github.com/datarat-sound). Forked from
[wstierhout/ableton-live-mcp](https://github.com/wstierhout/ableton-live-mcp)
(Wouter Stierhout), which builds on the original AbletonMCP by Siddharth Ahuja.
MIT licensed; see [LICENSE](LICENSE).

Ableton and Live are trademarks of Ableton AG. This project is not affiliated with
or endorsed by Ableton.