# Better Ableton MCP

[Documentation](https://michaelcortese.github.io/better-ableton-mcp/) · [Example conversations](https://michaelcortese.github.io/better-ableton-mcp/examples/) · [Complete tool index](https://michaelcortese.github.io/better-ableton-mcp/tool-index/)

A custom Ableton Live MCP focused on keeping sets tidy and creating MIDI that
fits material already in the set. It combines the practical socket-based Live
control of [ahujasid/ableton-mcp](https://github.com/ahujasid/ableton-mcp) with
the composition direction of
[FabianTinkl/AbletonMCP](https://github.com/FabianTinkl/AbletonMCP), then adds an
organization layer designed for repeatable daily use.

## What works

- The upstream control surface: session/track inspection, MIDI/audio track and
  clip creation, note insertion, transport, browser loading, and Session-to-
  Arrangement duplication.
- `preview_session_sort`: classify the entire set without making changes.
- `sort_session`: one call to rename and recolor tracks, normalize generic clip
  names, and match clip colors to their tracks. The operation is grouped into a
  single Ableton Undo step and is safe to run repeatedly.
- `analyze_track_harmony`: infer key/mode and pitch-class weight from any list
  of MIDI tracks, using Session clips, Arrangement clips, or both. Tracks with
  Arrangement MIDI only are supported; Session clips are not required.
- `analyze_midi_progression`: detect one chord per non-empty MIDI bar locally,
  with optional chord-theory enrichment from the THIRI REST API.
- `reharmonize_chord_progression`: ask THIRI for alternate chord-symbol
  progressions using a selected reharmonization technique.
- `generate_for_tracks`: create a melody or chord clip whose scale and pitch
  choices come from the specified tracks. Supplying an Ableton Group Track
  automatically includes its descendants. Seeds make melody variants repeatable.
- `generate_chords_for_selected_audio`: analyze a warped, monophonic vocal or
  other audio phrase directly from its source audio—without converting it to
  MIDI—and create a meter-aware MIDI chord progression aligned to it. By
  default it analyzes the whole selected Arrangement clip; an Arrangement Loop
  can instead mark a shorter phrase.
- `preview_converted_midi_cleanup`: inspect noise from Ableton's Convert Melody
  or Harmony to MIDI without changing the clip.
- `clean_converted_midi`: conservatively remove conversion artifacts across
  Session and Arrangement clips in one Ableton Undo step.
- No analytics or usage telemetry.

Track reordering is intentionally not automated because Ableton's documented
Live Object Model does not expose moving or grouping existing tracks.

## Install

Requires Ableton Live 11 or 12 and Python 3.10+.

1. Copy the `BetterAbletonMCP_Remote_Script` folder into your User Library's
   `Remote Scripts` folder. On Windows this is commonly:

   ```text
   %USERPROFILE%\Documents\Ableton\User Library\Remote Scripts\
   ```

2. Restart Live, then choose **BetterAbletonMCP_Remote_Script** under
   Preferences → Link, Tempo & MIDI → Control Surface. Leave Input and Output
   as `None`.

3. From this repository, install the server:

   ```powershell
   py -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -e .
   ```

   To generate chords from selected audio, install the optional local audio
   analysis dependencies instead:

   ```powershell
   pip install -e ".[audio]"
   ```

   Optional hosted theory and voicing features use the official THIRI REST API
   at `https://chords.thiri.ai`. Create and rotate credentials through
   [THIRI Innovate](https://build.thiri.ai/innovate/). Use `.env.example` as a
   reference and set `THIRI_API_KEY` in the environment used to launch the MCP
   server; `.env` is not loaded automatically. Never commit the key. Rotate any
   key pasted into chat before use.

4. Add the server to an MCP client. Use absolute paths:

   ```json
   {
     "mcpServers": {
       "better-ableton": {
         "command": "C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe",
         "args": ["-m", "better_ableton_mcp.server"],
         "cwd": "C:\\absolute\\path\\to\\better-ableton-mcp"
       }
     }
   }
   ```

The Remote Script listens on TCP port `9877` by default. Override the client
side with `ABLETON_HOST` and `ABLETON_PORT` environment variables.

## Example requests

```text
Preview how you would organize this Ableton set.
Sort this set: normalize the names and colors of tracks and clips.
Analyze the harmony in tracks 2, 3, and 6.
Detect the chord progression in MIDI track 2, one chord per four-beat bar.
Reharmonize C, Am, F, G using modal interchange.
Create an 8-bar melody that goes with tracks 2 and 3; use seed 17.
Create a 4-bar chord clip for the MIDI material in tracks 1, 4, and 5.
Make a chord progression that goes with the selected vocal clip.
Preview cleanup of the converted melody on track 7 at strength 0.5.
Clean the converted harmony on track 4, preserving chords.
```

Track and clip indices are zero-based at the protocol level. Ask for session
information first when the intended tracks are ambiguous.

For the selected-vocal request, click a warped Arrangement audio clip so it is
shown in Clip View. The audio must be monophonic, use any Warp mode except
Re-Pitch, and be readable from the machine running the MCP server. Audio
decoding, pitch detection, and chord selection stay local, and no intermediate
MIDI transcription is created. With the default `theory_provider="auto"`, a
configured THIRI key is used only to voice the locally chosen chord symbols;
raw audio, track names, and clip names are never sent. Without a key, the tool
uses local triads. The defaults (`selection_mode="clip"`, `bars=0`) analyze the
whole clip, create a new MIDI track, and put an exact-duration MIDI chord clip
at the audio clip's start; no instrument is loaded. To analyze only a phrase,
set and enable Live's Arrangement Loop with **Cmd-L**/**Ctrl-L** and use
`selection_mode="loop"`. Analysis is limited to 300 seconds of source audio per
request.

## Organization conventions

The default palette uses seven stable categories: drums (`10 DRM`), bass
(`20 BAS`), music (`30 MUS`), vocals (`40 VOX`), effects (`50 FX`), references
(`60 REF`), and utility tracks (`70 AUX`). Classification considers the track
name, parent group name, track type, and device names. Edit `CATEGORIES` and
`KEYWORDS` in `src/better_ableton_mcp/organization.py` to match your template.

## Development

```powershell
pip install -e ".[dev,audio]"
pytest
ruff check src tests
```

The harmony and organization engines are pure Python and can be tested without
Ableton. Live integration requires Live to be running with the Remote Script
enabled.

### Converted MIDI cleanup

The cleaner targets common audio-to-MIDI artifacts rather than simply deleting
everything outside a scale. It detects very short isolated blips, weak and rare
pitches, implausible register outliers, overlapping same-pitch fragments, and
extra simultaneous pitches in melody conversions. Harmony mode preserves
polyphony. `auto` chooses between melody and harmony behavior from onset density.

Use `preview_converted_midi_cleanup` first and begin around the default strength
of `0.55`. A lower strength is more conservative. Applied cleanup is grouped into
one Ableton Undo step, so the original result can be restored immediately.

## License

MIT. See `LICENSE` and `NOTICE.md`.