# LiveSession MCP

**An AI production assistant for Ableton Live.** Compose, arrange and mix with Claude (or any MCP
client), with real measurements instead of guesses — and work with your Live Sets even when Live is closed.

LiveSession MCP is an independent project. It is not affiliated with or endorsed by Ableton AG;
Ableton and Live are trademarks of Ableton AG. It started as a fork of
[ahujasid/ableton-mcp](https://github.com/ahujasid/ableton-mcp) (MIT).

---

## What it does

| | |
|---|---|
| **Compose** | Chords by symbol or roman numeral, voice-led (close, open, spread, drop 2, shell, rootless, quartal) · melodies with phrase shapes · basslines that follow slash chords · drum patterns · euclidean rhythms and polymeters · motif development (invert, retrograde, augment, sequence, additive...) · a library of 45 named progressions searchable by genre and mood · genre song starters |
| **Arrange** | Song structure from scenes with locators (clips cut exactly at section ends) · arrangement clips · take lanes · warp markers |
| **Sound** | Your installed plug-ins by *role* ("a plate reverb", "a warm compressor") from a scanned catalogue · Live's devices with ready-dialled chain recipes · Drum Rack pads · Simpler · presets · plug-in windows |
| **Mix with measurements** | Integrated loudness (LUFS), true peak, loudness range, tonal balance, stereo correlation, key — from your actual bounce · match a commercial reference and get the EQ moves applied · gain staging from Live's meters · sidechain · mix snapshots |
| **Live's menu** | Save, freeze, bounce in place, group, open the export dialog — things Live's API can't do, run through Live's own menu |
| **Files (Live closed)** | Summarise a Live Set · lint it before sharing (missing samples, plug-ins not installed, tracks routed nowhere...) · diff two versions · export MIDI clips · look inside .adg/.adv presets |
| **Safe by design** | Every tool is marked read-only or destructive · batches run as one undo step · the set is saved before deleting actions so Live keeps the previous version · a journal of every destructive call |

148 tools in 10 groups, 6 workflow prompts, server instructions for the model. Load only the groups you
need (`LIVESESSION_TOOLSETS=core,compose,mix,listen`) — fewer tools means better tool choices.

## Requirements

- Ableton Live 12 (recommended) or Live 11 — Suite, Standard or Intro
- Windows 10/11 or macOS 12+
- Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended)

## Install

**1. Add the server to your MCP client.** For Claude Desktop / Claude Code, in the MCP config:

```json
{
  "mcpServers": {
    "livesession": {
      "command": "uvx",
      "args": ["--from", "livesession-mcp[all]", "livesession-mcp"]
    }
  }
}
```

`[all]` adds listening (loudness analysis) and plug-in scanning. Without extras the core still works.

**2. Install the Remote Script into Live** (once, and after each upgrade):

```bash
uvx --from livesession-mcp livesession-mcp install
```

**3. In Live:** restart Live, open *Settings → Link, Tempo & MIDI*, choose **AbletonMCP** as a Control
Surface (Input and Output: None).

**4. Check everything:**

```bash
uvx --from livesession-mcp livesession-mcp doctor
```

`doctor` checks Python, the installed script version, the connection to Live, the optional extras and
your folders, and tells you how to fix anything that isn't right (`--json` for scripts).

On macOS, allow your MCP client (Claude, Terminal...) in *System Settings → Privacy & Security →
Accessibility* so menu commands and window pictures work.

## Try it

- "Start a mizrahi pop song in A minor at 96 BPM."
- "Give me a sad progression for the pre-chorus and write it on the piano with rootless voicings."
- "Take the melody in slot 1 and make a sequence a step higher in the next slot."
- "I exported the mix — how does it compare to this reference? Fix the tonal balance."
- "Lint my project folder before I send it to the mixing engineer."
- "What changed between today's version and the backup from this morning?"

Prompts ready to use: `start_a_song`, `make_a_beat`, `mix_and_master`, `analyze_and_improve`,
`prepare_for_collaboration`, `sound_design`.

## Configuration

```bash
livesession-mcp config show
livesession-mcp config set listen_dir "D:/Bounces"
livesession-mcp config set toolsets core,compose,mix,listen
livesession-mcp config set backup_before_destructive false
```

| Setting | Environment variable | Default |
|---|---|---|
| `listen_dir` — where you export bounces for listening | `LIVESESSION_LISTEN_DIR` | `~/Music/LiveSession/Listen` |
| `catalog_dir` — plug-in catalogue, snapshots, layouts | `LIVESESSION_CATALOG_DIR` | app data folder |
| `toolsets` — groups to expose | `LIVESESSION_TOOLSETS` | `all` |
| `backup_before_destructive` | — | `true` |
| `host` / `port` of the Remote Script | `ABLETON_HOST` / `ABLETON_PORT` | `localhost` / `9877` |

Tool groups: `core`, `compose`, `arrange`, `sound`, `mix`, `audio`, `listen`, `studio`, `files`, `advanced`.

## What Live's API can't do (and what LiveSession does instead)

- **Export**: no API. `prepare_export` sets the range and opens the dialog; `listen_latest` analyses the result.
- **Save, freeze, bounce, group**: no API — run through Live's own menu. Grouping several tracks needs them
  selected by mouse first (the API selects one track).
- **Third-party plug-in parameters**: only those exposed in Live (Configure). The catalogue knows every
  parameter, and `process_audio_with_plugins` renders audio through any plug-in offline.
- **Arrangement automation and tempo automation**: not reachable — use clip automation.
- **Detaching a groove** from a clip: not possible through the API; prefer `swing_clip`.
- Open dialogs in Live (including trial reminders) block the script until closed.

## Privacy and security

Nothing leaves your computer: no usage data is collected (see [TERMS.md](TERMS.md)). The Remote Script
listens on `127.0.0.1:9877` only and has no authentication — never forward that port. Your MCP client and
model provider handle your prompts under their own terms. See [SECURITY.md](SECURITY.md).

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
python -m MCP_Server.remote_script_install --sync-bundle   # after editing AbletonMCP_Remote_Script/
```

The Live-side `studio_ext.py` hot-reloads without restarting Live (copy it next to the installed script
and send `ext_reload_studio`). See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).

## License

MIT — see [LICENSE](LICENSE). Original work © Siddharth Ahuja; LiveSession MCP © Uri Rosen.