Connect to the MuseScore WebSocket API.

Ping the MuseScore WebSocket API to check connection.

Get the notes of the current score as LilyPond (or raw JSON), a range of measures at a time. Without end_measure, returns at most 16 measures starting at start_measure; the header says how many measures the score has, so page through long scores. Use staves to read only some staves of a large score. Each bar ends with '% m.N': N is the bar's position, which is what every tool's measure parameters mean. When the score's displayed bar numbers differ (e.g. they count repeats), the displayed number follows as '(bar M)'; repeat barlines show as '|:' and ':|xN'.

Get information about the current cursor position.

Navigate to a specific measure and select it across all staves. The cursor moves to beat 1 of that measure on the first staff, so the next cursor tool (add_note, add_rest, add_lyrics, set_time_signature...) acts there; use next_staff to move down to another staff.

Navigate to the final measure of the score.

Navigate to the beginning of the score.

Move cursor to the next element.

Move cursor to the previous element.

Move cursor to the next staff.

Move cursor to the previous staff.

Select the current measure.

Select a custom range of ticks across staves. Useful for retrieving continuous phrasing that spans measure boundaries.

Add a note at the current cursor position with the specified pitch and duration. Sequential notes write a melody. Set add_to_chord=True to stack a pitch on the current chord.

Tie notes of the chord at the cursor to the same pitches in the next chord of that staff. A tie joins two notes of the same pitch into one longer sound. Only pitches in both chords can be tied: by default every such pitch is tied; pass pitches to tie only some of them (e.g. tie C and E of C-E-G into C-E-A with pitches=[60, 64]). Afterwards the cursor is on the second chord, so calling add_tie again continues a tie chain. Note that after add_note the cursor is already on the next position: move back to the first note (e.g. with prev_element) before calling add_tie. Write both chords completely before tying: MuseScore treats tied chords as one, so a pitch added afterwards with add_note(add_to_chord=True) to the second chord is also added, tied, to the first. While writing music, add_tied_note is usually simpler. Fails without changing the score when no pitch can be tied, e.g. when the next element is a rest.

Write the next note or chord at the cursor, tied to the chord before the cursor: like pressing + in MuseScore's note input. Use it after add_note to hold a note longer, e.g. across a barline. By default the new chord repeats every pitch of the chord before it, all tied; pass pitches to tie only some of them, and extra_pitches for new pitches in the same chord without a tie (e.g. C-E-G into C-E-A: pitches=[60, 64], extra_pitches=[69]). Add new pitches this way, not with add_note(add_to_chord=True) afterwards: MuseScore treats tied chords as one and would also add the pitch, tied, to the chord before. A note longer than the rest of the bar is split at the barline into tied notes, and the cursor moves past all of it. Fails without changing the score when there is no note before the cursor or a pitch is not in it.

Add a rest at the current cursor position.

Add a tuplet at the current cursor position.

Add lyrics to consecutive notes starting from the current cursor position.

Insert a measure at the current position.

Append measures to the end of the score.

Delete the current selection, or the specified measure.

Remove whole measures (on every staff) from the score, like MuseScore's Remove selected range (Ctrl+Del). Works with multi-measure rests on (they are switched off meanwhile) and reports an error if MuseScore deleted fewer measures than asked. Later measures are renumbered, so when removing several ranges start from the last one.

Undo the last action.

Add a new staff/instrument to the score.

Mute or unmute a staff.

Change the sound of an instrument on a staff.

Set the time signature.

Set the tempo with a tempo marking (in quarter-note beats per minute) at the current cursor position, or at the start of the given measure.

Run several score commands in order in a single call. Each item is {"action": , "params": {...}}, using the same camelCase action names and parameters as the plugin (e.g. "addNote" with pitch, duration, advanceCursorAfterAction). Allowed actions: getScore, addNote, addTie, addTiedNote, addRest, addTuplet, appendMeasure, deleteSelection, getCursorInfo, goToMeasure, nextElement, prevElement, nextStaff, prevStaff, selectCurrentMeasure, insertMeasure, goToFinalMeasure, goToBeginningOfScore, setTimeSignature, addLyrics, addInstrument, setStaffMute, setInstrumentSound, setTempo, selectMeasures, deleteMeasures, setRepeatBarlines, addVolta, colorRange, setStyle, addRehearsalMark, removeParts, addHighlight, addLabel, clearHighlights, highlightNotes, highlightMarkings, highlightSymbols, setMeasureNumbering, numberAsPlayed, addText, removeAnnotations, addArticulation, removeArticulations, ghostNotes, beamOverRests, addSectionCounts. Measure ranges use startMeasure/endMeasure (1-based, inclusive) and startStaff/endStaff (0-based, endStaff exclusive). Processing stops at the first invalid action.

Show the current score as rendered sheet music in an interactive viewer. Use it to check your edits visually. Tuplet brackets and ties are not drawn. Hosts without MCP Apps support only receive a short text summary; use get_score for the note data.

Find repeated material in the score. Returns (1) per-staff bars that repeat the previous 1, 2 or 4 bars, candidates for measure-repeat signs (these declutter the page but keep the length), and (2) whole-score passages played again right away, candidates for repeat barlines and 1st/2nd endings (these shorten the score once the duplicate measures are deleted). Each passage lists the tool calls that apply it. Reads the score in small chunks, so it works on large scores. Measure numbers refer to the score as it is now: apply passages from the last one backwards.

Put start and end repeat barlines around a range of measures, or remove them. Needs MuseScore 4.6 or newer; on older versions the measures are selected and the reply says which palette items to click.

Add a volta (1st/2nd ending bracket) over a range of measures. Experimental: the plugin API has no dedicated volta call, so check the result; if it fails, the measures are selected and the reply says which palette item to click.

Prepare measure-repeat signs: selects the measures that should become repeat signs, on the given staves, and returns what to click in MuseScore. The plugin API cannot place measure-repeat signs itself.

Map the sections of a groove-based part (drums by default): for each section the groove bar, the bars that copy it exactly, near copies (with the hits that differ), and fills. Proposes measure-repeat signs for exact copies only, as ready-made apply_measure_repeats groups, and a collapse_to_repeat range for a 'groove bar x N' chart. Show near copies to the user and only replace them once approved: a repeat sign deletes their differences.

Outline the song for a structure page: the sections (from the rehearsal marks) with how many bars each lasts as played (repeats counted), the grooves in it (bars that recur, named Groove A, B... with the drums they use; hi-hat openings, crashes and ghost notes don't make a new groove) and the fills (bars that don't recur). Each section's count is its length in fours as drummers count it (6 -> '4+2', 12 -> '3x4', bars before the first groove bar counted on their own: '2+4+2'); bars excluded from the bar count (a count-in) are left out. suggested_rows can go to set_song_structure as they are, but give the grooves and fills musical names first (e.g. 'Verse shuffle', 'Tom fill into chorus').

Write each section's bar count (e.g. '2x4+2'). placement='label' (default, the chart style the user chose) puts it in parentheses in the section label (rehearsal mark): 'Chorus 1 (2x4)', and sets the labels to label_size points with label_clearance spaces around them, so MuseScore places and spaces them. placement='beside' writes it in bold red right of the label at the label's height (moved past a text already there or up over notes); MuseScore doesn't leave room for it between systems, so it can run into dynamics of the system above: only on request. Without counts, uses song_structure's counts (the ones already written in the labels where they still add up). Running it again replaces the counts in either form; clear=True removes them.

Collapse a run of repeated bars or phrases into one played N times: keeps the first phrase_bars bars from start, deletes the rest of the run, and puts start/end repeat barlines with a play count around the kept bars (shown as e.g. '7x'). With phrase_bars=2, bars start..end must be a 2-bar phrase repeated (e.g. 28-35 becomes 28-29 x4). This changes every staff, so use it in a score that contains only the part being charted (make_part_score). It refuses when any staff's copies differ in anything but ghost notes and crashes on beat 1, unless force=True. Later measures are renumbered: collapse from the end of the score backwards. Needs MuseScore 4.6+.

Make a separate score containing only some parts (e.g. the drum kit) to build a chart in: saves the current score, writes a copy of its file without the other instruments (tempo, rehearsal marks, repeats and the title move to the kept staff), closes the original and opens the copy in its place (the plugin can only work in its own window). The original is saved and unchanged; if the copy can't be opened, the original is reopened. Works even when another instrument has a damaged bar. in_place=True instead removes the other instruments from the open score itself, without saving anything first (so a damaged bar in another instrument is never written again) and after backing up the full score (MusicXML export, plus a copy of its .mscz when it can be identified); it reports bars left that don't add up. Staff indices in the new score start again from 0.

Make the displayed bar numbers count repeated bars, as played: after a passage between repeat barlines played N times, the next bar's number jumps by (N - 1) x the passage length. Recomputes all bars (MuseScore's 'Add to measure number'), so it can be run again after changing repeats. exclude_from_count leaves bars out of the count, e.g. [1] for a silent pickup or intro bar. reset=True removes all offsets and exclusions instead (plain 1..N numbering). Voltas are not taken into account. Needs MuseScore 4.6+. Tools keep addressing bars by position.

Set the displayed number of one bar: add_to_number is MuseScore's 'Add to measure number' (the offset carries on to all later bars), exclude_from_count is 'Exclude from measure count'.

Add a rehearsal mark (section label such as 'A' or 'Verse') at the start of a measure. Experimental: check the score afterwards.

Color the notes and rests (with their stems, beams, accidentals, dots, ties and grace notes such as flams) in a range of measures and staves, e.g. to highlight a passage. Use start_beat/end_beat to color only part of a bar, e.g. a fill on beats 3-4: notes and rests starting in that span are colored.

Reset notes and rests in a range of measures and staves (optionally only some beats) to the default black.

Highlight bars like a highlighter pen: a thick, semi-transparent band behind the notes of each staff in the range, following the bars across line breaks. start_beat/end_beat limit it to part of a bar. Saved in the score; remove with clear_highlights. Experimental: check the result in the score.

Highlight individual hits like a highlighter pen: a translucent box around each matching note, as wide as the note and as tall as the whole staff (taller if the note sits above or below it). Hits close enough for their boxes to touch share one box. Use drums (e.g. ["crash"]) or pitches to pick notes in a chord. start_beat/end_beat limit it to part of a bar. Boxes are sized to the current layout: if the layout changes a lot, clear and highlight again. Remove with clear_highlights.

Highlight or recolor time signatures, repeat barlines (start/end repeat signs with their dots) and measure-repeat signs. mode='highlight' draws a full-staff-height translucent box around each one (pastel light blue by default); mode='color' recolors the symbol itself (clear=True resets it to black).

Highlight markings such as dynamics (f, mf, ff) with a translucent box behind each one. get_score lists the markings in each measure. Remove with clear_highlights.

Add free text at a bar (optionally at a beat) with its own look: size, italic/bold, color, above or below the staff. Defaults give a small, italic, light-grey cue, e.g. the first words of a section's lyrics as a reminder for the player. kind='expression' makes it an expression text. Use the text the user provides. Remove with Ctrl+Z, or select the texts in MuseScore and delete them.

Remove texts and marks from a range of bars, e.g. to redo part of a chart. kinds: 'texts' (add_text: cues, '*' marks, legends), 'labels' (boxed add_label texts), 'rehearsal_marks', 'tempo' (tempo markings, which also changes playback), 'voltas'. contains limits it to texts containing that string, e.g. '**'. Defaults to the whole score. Highlights and note colors are removed with clear_highlights / clear_color instead.

Add an articulation to the chords that contain the chosen drums in a range of bars (and beats): 'half_open' (half-open hi-hat), 'open', 'closed' (hi-hat), 'accent', 'marcato', 'staccato', 'tenuto'. E.g. drums=['hi-hat'], symbol='half_open' marks the hi-hats of bars 72-85 as half-open. Chords that already have it are left alone. Remove with remove_articulations.

Remove articulations (by default the hi-hat symbols half_open, open, closed) from the chords that contain the chosen drums in a range of bars.

List the ghost notes (notes in parentheses) per bar, or remove them (mode='remove'). A chord made only of ghost notes becomes a rest. Show the list to the user before removing: whether a chart keeps ghost notes is their choice.

Beam eighths and shorter across rests inside a beat group (a dotted quarter in 12/8, a beat in 4/4), as drum charts write them: one beamed group per beat with the rest under the beam, instead of separate flags broken at every rest. Only rests with beamable notes before and after them in the same group change. Run it over the whole drum staff once the chart is done. clear=True puts the rests back on automatic beaming.

Add a label in a colored box (a boxed staff text) at the start of a measure, e.g. a section tag like 'Groove x7' or 'Fill'. Saved in the score; remove with clear_highlights.

Remove highlights from a range of measures and staves. kinds: 'highlights' = bands and boxes from highlight_bars, highlight_notes and highlight_symbols; 'markings' = boxes behind dynamics (highlight_markings); 'labels' = boxed labels (add_label); 'notes' = small notehead boxes made by older versions. Recolored notes and symbols are reset with clear_color / highlight_symbols(mode='color', clear=True).

Turn bars of one staff into measure-repeat signs (1-, 2- or 4-bar) automatically. MuseScore's plugin API cannot place these signs, so this saves the score, backs the file up, writes the signs into the file and reloads it in MuseScore. The reload resets MuseScore's undo history: use restore_backup to undo. Each sign repeats the bars just before it, and the replaced bars' notes are deleted. Bars with ties or slurs crossing their barlines are skipped and reported. Pass all groups for a staff in one call.

Rewrite a cymbal roll (a run of repeated or tied cymbal notes, e.g. a crash swell) as one long note per bar, tied across barlines, with a tremolo: the same sound with far fewer symbols. The roll starts on start_beat of start_measure (default beat 1; earlier notes in that bar stay as written) and ends at the end of end_measure, or after end_beat in it. Lengths that no single note value can hold are written as tied notes. Notes of the first chord that are not part of the roll (e.g. a kick) move to voice 2 with their own length. Refuses (changing nothing) if other notes or rests sit inside the roll or it doesn't start and end where notes do. Edits the score file and reloads it (undo with restore_backup).

Tidy the title frame at the top of the score: title, subtitle, composer, lyricist and the part name shown top-left in part scores (a long part name such as 'Player | Kit | Drums' runs into the title). Leave a field out to keep it, pass an empty string to remove it. Edits the score file and reloads it (undo with restore_backup).

Print notes at the end of the score, in a text frame after the last bar: a bold heading and one line per item, e.g. a summary of how a chart differs from the original (what was collapsed, which differences were dropped, what stays written out). Replaces notes added before (the report's previous lists them), so it can be re-run; append=True keeps their lines and adds the new ones; no heading and no lines removes them. Edits the score file and reloads it (undo with restore_backup).

Print the song structure as a table on a new page at the end of the score, after the end notes: the song and artist under the heading (taken from the title frame unless given), then one row per section with its bars (as played), groove and fills, and the total. Get the rows from song_structure and give grooves and fills musical names. Replaces a structure page added before; no rows removes it. Edits the score file and reloads it (undo with restore_backup).

Bring back the version of the open score saved before an apply_measure_repeats edit (the newest backup by default) and reload it in MuseScore. The current version is backed up first.