mcp-server-ableton-live
README.md
<!-- mcp-name: io.github.datarat-sound/ableton-mcp--datarat -->
# ableton-mcp--datarat
[](LICENSE)
[](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues