REAPER MCP

Get information about a media item. Returns: Object with item properties (position, length, take info, etc.).

Get all markers in the project. Returns: Object with list of markers (position, name, index).

Get information about the master track.

Get information about a MIDI item. Returns: Object with item info including position, length, note count.

Get all MIDI notes from an item. Returns: Object with list of notes.

Get the current playback position. Returns: Object with play position in seconds.

Get the current playback state. Returns: Object with play state info.

Get the length of the project (end of last item). Returns: Object with project length in seconds.

Get the project name.

Get the project path.

Get a comprehensive summary of the current REAPER project. Returns everything needed to understand the project state and give useful mixing/production advice in a single call. Returns: Object with: - project_name: Name of the project file - project_path: Full path to the project - tempo: Project tempo in BPM - time_signature: {numerator, denominator} - project_length: Length in seconds - track_count: Total number of tracks - tracks: List of track info objects, each containing: - index: Track index (0-based) - name: Track name - volume_db: Volume in decibels - pan: Pan position (-1 to 1) - mute: Boolean mute state - solo: Boolean solo state - fx_count: Number of FX plugins - fx_names: List of FX plugin names - master: Master track info {volume_db, fx_count, fx_names} - markers: List of {index, position, name} - regions: List of {index, start, end, name}

Get all regions in the project. Returns: Object with list of regions (start, end, name, index).

Get the current repeat state. Returns: Object with repeat state (true/false).

Get all selected media items. Returns: Object with list of selected items.

Read the MIDI notes currently SELECTED in REAPER's editor for the active take. The escape hatch for "operate on what I've selected": select notes by hand in REAPER, call this to see which they are, then translate that into an explicit value filter (pitch range / beat window / channel) for the transform tools. Read-only, no undo. Returns: {ok, notes:[...], ret} - the selected notes, same shape as get_midi_notes (each note carries item-relative start_beat/end_beat). `index` is REAPER's absolute PPQ-sorted note index, so a partial selection is non-contiguous. Empty selection -> notes:[].

Get indices of all selected tracks. Returns: Object with list of selected track indices.

List all takes of a media item. Returns: Object with 'takes' array (each entry: index, name, is_active) and 'ret' = take count.

Get the tempo at project start as `ret`, and every tempo marker as `tempo_markers`.

Get the current time selection. Returns: Object with start and end times.

Get the project time signature.

Get information about a track. Returns: Object with 'info': guid, name, volume, volume_db, pan, muted, soloed, has_midi, has_audio, fx_names, role.

Get the total number of tracks in the current REAPER project (excluding master track).

Get a track envelope by name. Args: envelope_name: Envelope name (e.g., "Volume", "Pan", "Mute"). Returns: Object with envelope info.

Get the raw state chunk from an FX plugin (includes preset/state data). Useful for reading VSTi state data like Toontrack EZkeys chord progressions. The chunk contains the full serialized state of the plugin. Returns: Object with 'chunk' containing the FX state data string.

Get all media items on a track. Returns: Object with list of items.

Get the master/parent send state of a track. Returns: Object with 'ret' field (1 = enabled, 0 = disabled).

Get the number of sends from a track.

Get the current peak level of a track. Args: channel: Channel (0=left, 1=right). Returns: Object with peak value in dB.

Get the peak hold level of a track (highest peak since meters were last reset). Returns the max peak from a previous playback without needing to be actively playing - play the project, stop, then call this for gain staging. Args: channel: Channel (0=left, 1=right). Returns: Object with peak hold value in dB.

Get the current undo/redo state. Returns: Object with undo and redo descriptions.

Move the edit cursor to a marker.

Move the edit cursor to a region start.

Humanize MIDI: nudge timing and velocity by small random amounts, reproducibly. Each note gets its own timing and velocity offset drawn from a bell curve. Note lengths are preserved (start and end move together) and pitches are never touched. The randomness is seeded, so the same take with the same seed and settings gives identical results every time. Velocities are clamped to 1-127 and counted in clamped; notes pushed past the item end are kept and reported in out_of_bounds. Unlike the other timing tools, a note pushed before the item start is placed at the item start and counted in out_of_bounds, not clamped; clamped here counts only the velocity clamp. Args: timing: Timing spread in beats (standard deviation); 0.02 is a subtle human feel, 0.0 leaves timing alone. velocity: Velocity spread (standard deviation, in velocity units); 0.0 leaves velocity alone. seed: Any integer. The same seed, settings and take give the same result. max_sigma: Cap on how far one note may stray, in multiples of the spread.

Insert an audio file onto a track. Args: file_path: Full path to the audio file. position: Position in seconds. Returns: Object with track_index, item_index of the created item, and position.

Insert a new track at the specified index. Args: index: Position to insert track (0-based). If not specified, adds at end. name: Optional name for the new track. Returns: Info about the created track.

Close the gaps in a MIDI line (legato), or set every note to one length. Only note ends move; starts are never touched. "connect" extends each note's end to the next onset and never shortens anything; a gap wider than max_gap_beats is left as a rest and counted in gaps_preserved, and the last note is left alone. "fixed" instead sets every targeted note's length to length_beats. Notes whose new end passes the item end are kept and reported in out_of_bounds. Args: mode: "connect" (extend each end to the next onset) or "fixed" (set every length). voice: connect only. "chordal" extends to the next onset of any note, so a chord's notes move together; "per_pitch" extends to the next note of the SAME pitch and channel, keeping interleaved voices independent. max_gap_beats: connect only. Gaps wider than this are left as rests (>= 0). length_beats: fixed only. The length every targeted note is set to (> 0). Returns: {ok, notes_changed, clamped, skipped, out_of_bounds, gaps_preserved, notes:[...]}.

Measure loudness as REAPER's loudness window does: integrated LUFS, short-term and momentary max, loudness range, sample peak, plus true peak. Target: the master (default), a track, or one item (its track's output over the item, other items muted). start_time/end_time limit it to a range. It runs a render dry run, so it writes no files, puts selections back and adds no undo step. Measuring the master marks the project as modified, even though nothing in it changes. Returns: integrated_lufs, short_term_max_lufs, momentary_max_lufs, loudness_range_lu, sample_peak_dbfs, true_peak_dbtp, samples_over_0dbfs, duration; a note when a figure is approximate or unavailable.

Measure tonal balance and stereo image: octave-band levels (31.5 Hz to 16 kHz), spectral centroid, tilt in dB per octave, stereo correlation overall and below 150 Hz, side-to-mid level and left/right balance. Same targets and range as measure_loudness. Levels are dBFS with a full-scale sine at 0, as in REAPER. Needs the TwelveTake MCP Analyzer, which --install-bridge installs.

Shift MIDI notes in time by a number of beats (+ = later, - = earlier). Start and end move together, so note lengths are preserved. A note pushed before the item start clamps to it and one pushed past the item end is left there; both count in `out_of_bounds`, not `clamped`. Args: amount_beats: Signed beat shift (0.25 = a 16th later, -1.0 = a beat earlier). 0 = no-op.

Open a REAPER project file. Args: path: Full path to the .rpp file.

Paste items from clipboard at edit cursor.

Pause playback in REAPER.

Start playback in REAPER.

Quantize MIDI note onsets onto the grid (tighten sloppy timing, add swing). Onsets snap to the PROJECT bar/beat grid, not to an offset from the item's own start, and note lengths are preserved: start and end move together. Notes that land past the item end are kept, and one that would land before the item start is placed at it; both are counted in `out_of_bounds` (`clamped` stays 0 here). Args: grid: Grid spacing in beats: 0.25 = 1/16, 0.5 = 1/8, 1.0 = 1/4. Must be > 0. strength: 0.0-1.0. 1.0 snaps exactly onto the grid, 0.5 moves each note halfway there, 0.0 is a no-op. swing: 0.0-1.0. 0.0 = straight, 1.0 = full triplet feel (off-beats at 66.7%), scaling linearly between. Only the off-beat (odd) grid cells are delayed.

Apply a linear velocity ramp (crescendo / decrescendo) across MIDI notes. Velocities interpolate by onset: the earliest note in the filtered set gets start_velocity, the latest gets end_velocity, everything between is linear. Notes sharing an onset (a chord) get the same velocity. Results clamp to 1-127. Args: start_velocity: Velocity at the earliest onset (1-127; out of range clamps, not an error). end_velocity: Velocity at the latest onset (1-127).

Start recording in REAPER.

Redo the last undone action in REAPER. Returns: Object with redo description.

Clean up overlapping MIDI notes (same pitch stacked on itself). Two notes conflict only if they share a pitch AND a channel AND overlap in time, so a chord is never a conflict and notes that merely touch are left alone. "trim" shortens the earlier note to stop where the next begins, losing nothing; "delete" drops one note of each overlapping pair, keeping the louder (ties go to the longer note). Either mode can remove notes: notes stacked on the exact same onset collapse to the loudest, since there is nothing to trim between them, and a trim left shorter than min_length_beats is removed rather than left as a click. Args: mode: "trim" (shorten the earlier note) or "delete" (drop the quieter note). min_length_beats: A trimmed note left shorter than this is removed instead. Default 1/128 of a beat; 0 disables it. pitch_low, pitch_high: Notes outside the filter are invisible: never touched, and never counted as an overlap partner. Returns: {ok, mode, notes_changed, clamped, skipped, out_of_bounds, notes_removed, trimmed, deduped, deleted, notes:[...]} where notes_removed = deduped + deleted.

Render the project's master mix to an audio file (uses REAPER's last render settings for format details; a .wav extension selects WAV output). If the target file already exists, this returns an error unless overwrite=True (which deletes the existing file first). This is explicit because REAPER's own behavior on existing files (prompt vs auto-increment) is a user preference, and the overwrite prompt blocks unattended rendering. Args: output_path: Full path for output file (extension determines format). start_time: Start time in seconds (None = project start). end_time: End time in seconds (None = project end). tail_seconds: Extra seconds to render at end for reverb tails. overwrite: True to replace an existing file at output_path. Returns: Object with render status and REAPER's computed output target(s).

NOT IMPLEMENTED. Use render_project with the region's start/end from get_regions. Args: output_path: Full path for output file.