Live control tools

These tools expose Ableton Live's set, Session View, browser, transport, and Arrangement View through the MCP server. They are the general-purpose control surface inherited from the upstream Ableton MCP projects; the organizer and harmony tools are documented separately.

Before you call a tool

Ableton Live must be running with BetterAbletonMCP_Remote_Script selected as a Control Surface. The MCP server connects to that script over TCP.
track_index and clip_index are zero-based. A clip_index identifies a Session View clip slot unless a tool explicitly says Arrangement View.
Beat positions and clip lengths use Live beats, not seconds. In 4/4, 0.0 is the start, 4.0 is bar 2, and 8.0 is bar 3.
Calls return text to the MCP client. Inspection tools embed JSON or a readable browser listing; mutation tools return a short confirmation.
Most tools accept an optional user_prompt string. It is server-side call context and is not sent to Live or used to change the operation. Clients can normally omit it.
Invalid indices, unsupported Live APIs, missing clips, and Remote Script connection problems are returned as Error ... text rather than raised to the MCP client.

When the target set is unfamiliar, call get_session_info and then get_track_info before making changes.

Session and track inspection

`get_session_info`

Read the current set's global state.

Parameters: no operation-specific parameters.

Returns: formatted JSON containing tempo, time-signature numerator and denominator, normal-track and return-track counts, Master volume and panning, and transport state: is_playing, current_song_time, song_length, loop, loop_start, and loop_length.

{}

Transport properties unavailable in a particular Live version fall back to a stable value (false or 0.0) instead of removing fields from the response. The track count does not include return or Master tracks.

`get_track_info`

Inspect one normal Live track, including its Session slots and devices.

Parameter	Type	Description
`track_index`	integer	Zero-based index in `song.tracks`.

{"track_index": 2}

Returns: formatted JSON with the track's index, name, audio/MIDI input capabilities, mute/solo/arm state, volume, panning, every Session clip slot, and every device. An occupied slot includes clip name, length, playing state, and recording state. A device includes index, name, Live class name, and an inferred type such as drum_machine, rack, instrument, audio_effect, midi_effect, or unknown.

Only normal tracks can be addressed; return and Master tracks are not in this index space. The device type is heuristic, so use its class name when exact identification matters.

Track creation and naming

`create_midi_track`

Create a normal MIDI track.

Parameter	Type	Default	Description
`index`	integer	`-1`	Insert position; `-1` appends after the last normal track.

{"index": -1}

The response reports Live's generated track name. Existing tracks at an explicit insertion index shift to the right.

`create_audio_track`

Create a normal audio track.

Parameter	Type	Default	Description
`index`	integer	`-1`	Insert position; `-1` appends after the last normal track.

{"index": 1}

The response reports Live's generated track name. This tool does not accept user_prompt.

`create_return_track`

Append and name a return track.

Parameter	Type	Default	Description
`name`	string	`"Return"`	Name assigned immediately after creation.

{"name": "Long Reverb"}

Live's API always appends return tracks, so there is no insertion index. The returned index is in the separate song.return_tracks collection. This tool does not accept user_prompt.

`set_track_name`

Rename a normal track.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`name`	string	New track name.

{"track_index": 0, "name": "Lead Synth"}

Return and Master tracks cannot be targeted by this tool.

Session clips and MIDI notes

`create_clip`

Create an empty MIDI clip in a Session View slot.

Parameter	Type	Default	Description
`track_index`	integer	required	Zero-based normal-track index.
`clip_index`	integer	required	Zero-based Session slot index.
`length`	number	`4.0`	Clip length in beats.

{"track_index": 0, "clip_index": 0, "length": 8.0}

The target must support MIDI clips and the slot must be empty. Live rejects an invalid length, an audio track, or an occupied slot. This tool creates the clip only; use add_notes_to_clip to populate it.

`create_audio_clip`

Import an audio file into an empty Session View slot on an audio track.

Parameter	Type	Description
`track_index`	integer	Zero-based normal audio-track index.
`clip_index`	integer	Zero-based Session slot index.
`path`	string	Absolute filesystem path to a Live-supported audio file.

{
  "track_index": 1,
  "clip_index": 0,
  "path": "C:\\Samples\\field-recording.wav"
}

Requires Ableton Live 12.0.5 or newer because it uses ClipSlot.create_audio_clip. The path is interpreted by the machine running Live, must be absolute, and must be readable there. The target must be an audio track and the slot must be empty. Import can take longer than other operations; the Remote Script allows up to 60 seconds for this command. The confirmation includes the resulting clip name and length.

`add_notes_to_clip`

Add MIDI notes to an existing Session clip.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`clip_index`	integer	Zero-based Session slot index.
`notes`	array	Note objects described below.

Each note object accepts:

Field	Type	Default	Description
`pitch`	integer	`60`	MIDI note number, normally 0–127.
`start_time`	number	`0.0`	Start position in beats relative to the clip.
`duration`	number	`0.25`	Duration in beats.
`velocity`	number	`100`	MIDI velocity, normally 1–127.
`mute`	boolean	`false`	Whether the note is muted.

{
  "track_index": 0,
  "clip_index": 0,
  "notes": [
    {"pitch": 60, "start_time": 0.0, "duration": 1.0, "velocity": 96, "mute": false},
    {"pitch": 64, "start_time": 1.0, "duration": 1.0, "velocity": 92, "mute": false}
  ]
}

The slot must already contain a MIDI clip. This calls Live's set_notes with the supplied notes; it adds them to the clip and does not provide the all-notes replacement workflow used by the separate MIDI cleanup feature. Live performs final range and validity checks.

`set_clip_name`

Rename an existing Session clip.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`clip_index`	integer	Zero-based Session slot index.
`name`	string	New clip name.

{"track_index": 0, "clip_index": 0, "name": "Verse Chords"}

The slot must contain a clip. Arrangement clips cannot be renamed with this tool.

Tempo and transport

`set_tempo`

Set the set tempo in beats per minute.

Parameter	Type	Description
`tempo`	number	Desired BPM.

{"tempo": 124.0}

Live enforces its supported tempo range. This changes the set immediately.

`fire_clip`

Launch a Session View clip using Live's normal clip-launch behavior.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`clip_index`	integer	Zero-based Session slot index.

{"track_index": 2, "clip_index": 3}

The slot must contain a clip. Global quantization and the clip's launch settings still apply, so playback may begin on a later beat.

`stop_clip`

Stop playback for a Session slot.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`clip_index`	integer	Zero-based Session slot index.

{"track_index": 2, "clip_index": 3}

This calls ClipSlot.stop() and does not require the slot to contain a clip. Live's launch quantization may affect when the stop takes effect.

`start_playback`

Start Live's global transport from the current song time.

{}

This uses Song.start_playing; it does not reset the playhead or select a particular Session scene.

`stop_playback`

Stop Live's global transport.

{}

This uses Song.stop_playing; it does not move the playhead back to zero.

Live browser and device loading

Browser content varies with the installed Live edition, Packs, User Library, plug-ins, and Live version. Discover paths and URIs in the same Live instance where the item will be loaded.

`get_browser_tree`

List available browser root categories.

Parameter	Type	Default	Description
`category_type`	string	`"all"`	`all`, `instruments`, `sounds`, `drums`, `audio_effects`, `midi_effects`, or another browser attribute exposed by Live.

{"category_type": "instruments"}

The MCP response is a readable bullet list, not raw JSON. Despite the tool's historical name, the current Remote Script returns a shallow root-category summary; use get_browser_items_at_path to descend through folders. A category missing from this Live installation produces a message listing the available browser attributes.

`get_browser_items_at_path`

Inspect the immediate children of a browser category or folder.

Parameter	Type	Description
`path`	string	Slash-separated browser path, beginning with a root category.

{"path": "instruments/Analog"}

Matching is case-insensitive by display name. Empty path components are ignored. The formatted JSON response describes the selected item (path, name, uri, is_folder, is_device, and is_loadable) and an items array with those fields for each immediate child.

Use root names such as instruments, sounds, drums, audio_effects, or midi_effects; additional Live browser attributes may also work. Paths depend on localized display names and installed content. The tool reports the first missing component, a non-folder component, or available roots when navigation fails.

`load_instrument_or_effect`

Load a browser item onto a normal track by URI.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.
`uri`	string	Exact URI returned by Live's browser.

{
  "track_index": 0,
  "uri": "query:Synths#Instrument%20Rack:Bass:FileId_5116"
}

The Remote Script selects the target track, searches the browser, and asks Live to load the matching item. The search includes the standard roots and, when exposed, plug-ins, Max for Live, User Library, Packs, and Samples. It is limited to 10 levels and successful URI lookups are cached for the Remote Script's lifetime.

The name is historical: any loadable browser item accepted by Live may be loaded, and Live determines the insertion position from its current browser loading rules. Use an exact URI from get_browser_items_at_path; a display path is not a URI. Large browser libraries can make a first lookup slow, and state-changing commands normally time out after 10 seconds.

`load_drum_kit`

Load a drum rack, then load a kit found at a browser path onto the same track.

Parameter	Type	Description
`track_index`	integer	Zero-based normal MIDI-track index.
`rack_uri`	string	Exact URI of the rack browser item.
`kit_path`	string	Slash-separated browser folder containing kits.

{
  "track_index": 0,
  "rack_uri": "Drums/Drum Rack",
  "kit_path": "drums/Acoustic"
}

The operation first loads rack_uri, gets the immediate children of kit_path, then loads the first child whose is_loadable flag is true. It does not select a kit by name and is not atomic: if path lookup or kit loading fails, the rack can remain loaded. Inspect the folder first when deterministic kit selection matters. Both loads use Live's browser and current loading behavior.

Arrangement View

`switch_to_arrangement_view`

Show Arrangement View in Live's main window.

{}

This changes the visible UI only; it does not start playback, move the playhead, or copy clips.

`set_arrangement_time`

Move the song playhead to a beat position.

Parameter	Type	Description
`time`	number	Absolute beat position from the start of the arrangement.

{"time": 16.0}

The response confirms Live's resulting current_song_time. The tool does not switch views or start playback. Live performs final validation of the value.

`get_arrangement_clips`

List every Arrangement clip on one normal track.

Parameter	Type	Description
`track_index`	integer	Zero-based normal-track index.

{"track_index": 0}

Returns: formatted JSON containing the track index and name, clip_count, and clips. Each clip contains name, start_time, end_time, length, color, is_midi_clip, is_audio_clip, and is_playing.

This relies on track.arrangement_clips, available in Live 11 and 12. Session clips are not included.

`duplicate_to_arrangement`

Copy an existing Session View clip to the Arrangement timeline on the same track.

Parameter	Type	Description
`track_index`	integer	Zero-based index of the normal track that owns the source clip.
`clip_index`	integer	Zero-based source Session slot index.
`destination_time`	number	Absolute destination beat in Arrangement View.

{"track_index": 0, "clip_index": 0, "destination_time": 16.0}

The source slot must contain a clip. Live duplicates the clip to the same track using Track.duplicate_clip_to_arrangement; it does not remove or alter the Session source. Existing Arrangement material is not cleared first, so the copy may overlap it. The API is available in Live 11 and 12. Call switch_to_arrangement_view afterward if you want Live to display the result.

Typical workflows

Create and launch a MIDI idea:

create_midi_track with {"index": -1}.
set_track_name with the returned track index.
create_clip in an empty Session slot.
add_notes_to_clip with the desired note objects.
set_clip_name, then fire_clip.

Build an Arrangement from a Session clip:

Inspect the source with get_track_info.
Call duplicate_to_arrangement once for each desired destination beat.
Confirm placement with get_arrangement_clips.
Call switch_to_arrangement_view to show it in Live.

Load a browser device safely:

Call get_browser_tree to learn the roots available in this installation.
Walk one folder at a time with get_browser_items_at_path.
Copy the desired loadable item's exact uri into load_instrument_or_effect.