ableton-mcp

A full-featured Model Context Protocol (MCP) server that gives AI assistants (Claude, etc.) complete control over Ableton Live via AbletonOSC.

Overview

ableton-mcp bridges AI assistants and Ableton Live by exposing 124 MCP tools covering every major area of the Live API: transport control, track mixing, clip launching and editing, MIDI note manipulation, device parameter control, scene management, view selection, and real-time property listeners.

The server communicates with Ableton Live via AbletonOSC — a MIDI Remote Script that runs inside Live and exposes its internal API over OSC/UDP.

Claude (AI) ──MCP tools──▶ ableton-mcp ──OSC/UDP──▶ AbletonOSC ──Live Object Model──▶ Ableton Live

---

Requirements

• Ableton Live 11 or later
• Python 3.10+ (tested with 3.10.6 via pyenv)
• AbletonOSC installed as a MIDI Remote Script (see below)

---

Installation

1. Install AbletonOSC in Ableton Live

1. Download or clone AbletonOSC
2. Copy the AbletonOSC folder into your Ableton User Library Remote Scripts directory:
   • Windows: %USERPROFILE%\Documents\Ableton\User Library\Remote Scripts
   • macOS: ~/Music/Ableton/User Library/Remote Scripts
3. Restart Ableton Live
4. Open Preferences → Link, Tempo & MIDI → MIDI and set one of the Control Surface slots to AbletonOSC

AbletonOSC will now listen on UDP port 11000 and reply on port 11001.

2. Install ableton-mcp

# Clone the repo (rename the folder after cloning)
git clone https://github.com/your-user/ableton-mcp
cd ableton-mcp

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

# Install
pip install -e .

3. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ableton": {
      "command": "C:\\path\\to\\ableton-mcp\\.venv\\Scripts\\ableton-mcp.exe"
    }
  }
}

Restart Claude Desktop. The Ableton Live tools will appear automatically when a Live session is open.

---

Configuration

All settings can be overridden via environment variables:

Variable	Default	Description
ABLETON_HOST	127.0.0.1	AbletonOSC host address
ABLETON_SEND_PORT	11000	Port to send OSC commands to Live
ABLETON_RECEIVE_PORT	11001	Port to receive OSC replies from Live
ABLETON_TIMEOUT	5.0	Query timeout in seconds

Example (Claude Desktop config with custom port):

{
  "mcpServers": {
    "ableton": {
      "command": "C:\\path\\to\\.venv\\Scripts\\ableton-mcp.exe",
      "env": {
        "ABLETON_TIMEOUT": "10.0"
      }
    }
  }
}

---

Tool Reference

System (7 tools)

Tool	Description
system_test_connection	Ping AbletonOSC; returns {connected, latency_ms}
system_get_version	Get Ableton Live version {major, minor}
system_get_cpu_usage	Get average CPU process usage (0.0–1.0)
system_show_message	Display a message in the Ableton status bar
system_get_log_level	Get current AbletonOSC log level
system_set_log_level	Set log level: debug / info / warning / error / critical
system_reload_api	Hot-reload all AbletonOSC modules

---

Song / Transport (48 tools)

Playback

Tool	Description
song_get_state	Full snapshot: tempo, is_playing, loop, time sig, track/scene counts, groove, link, scale…
song_start_playing	Start playback from current position
song_stop_playing	Stop playback
song_continue_playing	Resume without resetting to start
song_stop_all_clips	Stop all active clips
song_tap_tempo	Send a tap-tempo pulse

Tempo & Time

Tool	Description
song_get_tempo / song_set_tempo	Get/set BPM (20–300)
song_get_time / song_set_time	Get/jump playhead position in beats
song_get_time_signature / song_set_time_signature	Get/set numerator + denominator

Loop

Tool	Description
song_get_loop	Get {loop, loop_start, loop_length}
song_set_loop	Set on/off, start, and length (beats)

Metronome, Quantization & Groove

Tool	Description
song_get_metronome / song_set_metronome	Toggle metronome
song_set_quantization	Clip trigger quantization (0=none … 13=1/32)
song_set_midi_recording_quantization	MIDI recording quantization
song_set_groove	Global groove amount (0.0–1.0)

Recording

Tool	Description
song_set_arrangement_overdub	Enable/disable arrangement overdub
song_set_session_record	Enable/disable session record
song_set_punch_in / song_set_punch_out	Punch in/out
song_trigger_session_record	Toggle session record
song_capture_midi	Capture incoming MIDI into a new clip
song_re_enable_automation	Re-enable overridden automation

Edit

Tool	Description
song_undo / song_redo	Undo/redo

Tracks

Tool	Description
song_get_tracks	List all tracks with index and name
song_create_audio_track	Create audio track at index
song_create_midi_track	Create MIDI track at index
song_create_return_track	Create return/aux track
song_delete_track / song_delete_return_track	Delete track
song_duplicate_track	Duplicate a track

Scenes

Tool	Description
song_get_scenes	List all scenes with index and name
song_create_scene / song_delete_scene / song_duplicate_scene	Scene CRUD
song_capture_and_insert_scene	Capture session state as a new scene

Cue Points

Tool	Description
song_get_cue_points	List all cue points
song_jump_to_cue	Jump to cue by index or name
song_add_or_delete_cue	Toggle cue at current playhead
song_set_cue_name	Rename a cue point

Scale & Link

Tool	Description
song_set_root_note	Set root note (0=C … 11=B)
song_set_scale_name	Set scale name e.g. "Major", "Dorian"
song_set_ableton_link	Enable/disable Ableton Link
song_export_structure	Export full session structure to JSON file

---

Tracks (19 tools)

Tool	Description
track_get_info	All track properties: name, volume, pan, mute, solo, arm, type, color, monitoring, meter slots, device count
track_set_volume	Volume (0.0=−∞, 0.85≈0 dB, 1.0=+6 dB)
track_set_pan	Panning (−1.0=left, 0.0=center, +1.0=right)
track_set_mute	Mute / unmute
track_set_solo	Solo / unsolo
track_set_arm	Arm / disarm for recording
track_get_send / track_set_send	Get/set send level to a return track
track_set_name	Rename a track
track_set_color	Set track color by palette index (0–69)
track_stop_clips	Stop all clips on a track
track_set_monitoring	Monitoring state: 0=Auto, 1=In, 2=Off
track_set_fold	Fold/unfold a group track
track_get_clips	List session clips: index, name, length, color
track_get_arrangement_clips	List arrangement clips: index, name, length, start_time
track_get_devices	List devices: index, name, type, class_name
track_get_meter	Output meter levels: left, right, level
track_delete_device	Remove a device from the chain
track_get_available_input_routing_types	List available input routing options
track_set_input_routing_type / track_set_output_routing_type	Set I/O routing

---

Clips (19 tools)

Tool	Description
clip_fire	Launch a clip
clip_stop	Stop a playing clip
clip_get_info	All clip properties: name, length, playing state, loop, markers, pitch, gain, launch mode, warp, color
clip_set_name	Rename a clip
clip_set_color	Set clip color by palette index (0–69)
clip_set_gain	Set clip gain in dB
clip_set_muted	Mute/unmute a clip
clip_set_looping	Enable/disable loop
clip_set_loop_points	Set loop start + end in beats
clip_set_markers	Set start + end markers in beats
clip_set_pitch	Transpose: semitones (−48 to +48) and cents (−50 to +50)
clip_set_warp_mode	Warp mode: 0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 5=Complex Pro
clip_set_warping	Enable/disable warping
clip_set_launch_mode	Launch mode: 0=Trigger, 1=Gate, 2=Toggle, 3=Repeat
clip_set_launch_quantization	Per-clip launch quantization (0–14)
clip_set_legato	Enable/disable legato mode
clip_duplicate_loop	Double loop length by duplicating content
clip_get_notes	Get MIDI notes (filterable by pitch range + time range)
clip_add_notes	Add MIDI notes: [{pitch, start, duration, velocity, mute}, …]
clip_remove_notes	Remove MIDI notes by pitch/time range

---

Clip Slots (7 tools)

Tool	Description
clip_slot_get_info	Slot state: has_clip, is_playing, is_triggered, will_record, is_group_slot
clip_slot_fire	Trigger a slot (launches clip or starts recording if empty)
clip_slot_stop	Stop a slot
clip_slot_create_clip	Create a new empty MIDI clip with a given length in beats
clip_slot_delete_clip	Delete the clip in a slot
clip_slot_duplicate_to	Copy clip from one slot to another
clip_slot_set_stop_button	Enable/disable the stop button for a slot

---

Scenes (7 tools)

Tool	Description
scene_fire	Launch a scene by index
scene_fire_selected	Launch the currently selected scene
scene_get_info	All scene properties: name, color, tempo, tempo_enabled, time sig, is_empty, is_triggered
scene_set_name	Rename a scene
scene_set_color	Set scene color by palette index (0–69)
scene_set_tempo	Override tempo for a scene (with enable toggle)
scene_set_time_signature	Override time signature for a scene

---

Devices (6 tools)

Tool	Description
device_get_info	Device info: name, type (audio_effect / instrument / midi_effect), class_name, num_parameters
device_get_parameters	All parameters: index, name, value, min, max, is_quantized
device_get_parameter	Single parameter: name, value, value_string (display value)
device_set_parameter	Set a parameter value (normalized 0.0–1.0)
device_set_parameters_bulk	Set multiple parameters in one call: [{index, value}, …]
device_map_midi_cc	Map a MIDI CC to a device parameter

---

View / Selection (5 tools)

Tool	Description
view_get_selection	Current selection: selected_track, selected_scene, selected_clip, selected_device
view_set_selected_track	Select a track in the Ableton UI
view_set_selected_scene	Select a scene in the Ableton UI
view_set_selected_clip	Select a clip in the Ableton UI
view_set_selected_device	Select a device in the Ableton UI

---

Real-time Listeners (3 tools)

Subscribe to property changes from Ableton Live and poll them at any time.

Tool	Description
listener_start	Register a listener for a property; returns the OSC response address
listener_stop	Unregister a listener
listener_get_events	Drain queued events (up to max_events); each event is a list of OSC args

Supported objects and properties:

object_type	property_name	Notes
song	beat	[beat_number, beat_index, bar, song_time] per beat
song	is_playing	[0/1]
song	tempo	[bpm]
song	current_song_time	[beats]
view	selected_track	[track_index]
view	selected_scene	[scene_index]
track	any read/write property	requires track_index
clip	any read/write property	requires track_index + clip_index
clip_slot	any property	requires track_index + clip_index

Example usage with Claude:

"Watch the beat and tell me the bar number every 4 bars"
Claude calls listener_start("song", "beat"), then periodically listener_get_events("song", "beat")

---

Example Prompts

Play the song from bar 3 at 128 BPM with the metronome on.

Create a 4-bar MIDI clip on track 0, slot 1, and add a C minor chord
(C3, Eb3, G3) on beats 1 and 3 with velocity 90.

Set every device on track 2 to a random-ish sound: 
randomize all parameters whose name contains "Filter".

Loop scene 4 forever: set scene 4's clips to looping and fire the scene.

Solo track 3, mute tracks 1 and 2, and set track 3's reverb send to 0.4.

Name all empty scenes "—" and delete any track with no clips.

---

Architecture

src/ableton_mcp/
├── server.py        # FastMCP app; registers all tool modules
├── osc_client.py    # Thread-safe OSCClient singleton
│                    #   cmd()   – fire-and-forget
│                    #   query() – synchronous request/response
│                    #   start_listener() / drain_listener() – real-time events
├── config.py        # Port/host/timeout from env vars
└── tools/
    ├── song.py      # Transport, tempo, loop, scenes, tracks, cues, scale, Link
    ├── track.py     # Mixing, routing, devices list, meter
    ├── clip.py      # Playback, MIDI notes, pitch, warp, loop, launch
    ├── clip_slot.py # Slot-level create/fire/delete/duplicate
    ├── scene.py     # Scene fire, tempo/time-sig overrides
    ├── device.py    # Parameter get/set (individual + bulk), MIDI CC mapping
    ├── view.py      # Selected track/scene/clip/device
    ├── system.py    # Connectivity, version, CPU, status bar, logging
    └── listener.py  # Real-time property change subscriptions

OSC communication uses python-osc directly against AbletonOSC's full 200+ endpoint API. The OSCClient singleton runs a ThreadingOSCUDPServer on the receive port in a daemon thread. Queries use threading.Event for synchronous blocking with configurable timeout. Listeners store events in per-address collections.deque instances for thread-safe polling.

---

Troubleshooting

system_test_connection returns connected: false

• Confirm AbletonOSC is enabled in Ableton → Preferences → Control Surfaces
• Make sure a Live project is open (AbletonOSC only activates with an open set)
• Check that no firewall is blocking UDP 11000/11001 on localhost

Timeout errors on queries

• Increase ABLETON_TIMEOUT env var (default 5 s)
• Some properties (e.g. song_get_state) issue many sequential OSC queries; slow machines may need a higher timeout

No module named 'ableton_mcp'

• Make sure you installed with pip install -e . inside the correct .venv
• The Claude Desktop config command path must point to the .venv executable, not the system Python

---

License

MIT