Skip to main content
Glama

CI PyPI Integration Python 3.14+ License: MIT

mcp-score

Music notation for AI assistants. Describe a piece in plain language and get a MusicXML score; with MuseScore open, read and edit the live score by conversation.

Works with any MCP client (Claude Code, Claude Desktop, LM Studio, and others). Status: alpha.

Quick demo

"Create a big band chart: 32-bar AABA form, key of Bb, slow blues at 66 BPM, with rhythm changes and rehearsal marks at each section."

The assistant writes a complete music21 script, runs it, and hands you a MusicXML file ready to open in MuseScore, Dorico, or any notation app.

With the MuseScore plugin running, you can go further:

"Read the melody in bars 9-16 and arrange it as a trombone soli following the chord progression."

The assistant reads the live score, applies musical judgement, and writes the arrangement back, all through conversation.

Related MCP server: Dorico MCP Server

What it does

  • Generate scores. The assistant writes a music21 script that exports MusicXML, which opens in MuseScore, Dorico, or any notation app. In Claude Code this is driven by the bundled score-generate skill. In other MCP clients, the generate_score tool runs the script and score_generation_guide supplies the same instructions.

  • Edit live scores. MCP tools connect to a running MuseScore and read passages, add notes, dynamics and chord symbols, set barlines, keys, time signatures and tempo, append measures, transpose, and undo.

  • Render. The render_score tool exports PDF, PNG, MIDI, audio or MusicXML from a score file through the MuseScore command line; MuseScore must be installed but not running.

Supported applications

Application

Versions

Status

MuseScore Studio

4.4.2 and later

Supported; CI tests the oldest supported line, a middle release and the newest. Earlier versions lack the plugin WebSocket API.

Dorico

4 and later

Experimental. Undocumented Remote Control API, command-only, not verified against a running instance.

Any notation app

MusicXML import

Generated scores open anywhere MusicXML does.

Install

Requires Python 3.14 or later.

pip install mcp-score-server
# or
uv tool install mcp-score-server

Then:

mcp-score install-plugin   # MuseScore plugin, for live editing
mcp-score install-skill    # score-generate skill, for Claude Code

Connect your MCP client

Claude Code:

claude mcp add mcp-score -- mcp-score serve

Claude Desktop and other clients: run the command mcp-score with the argument serve, for example in claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-score": { "command": "mcp-score", "args": ["serve"] }
  }
}

Use it with MuseScore

  1. Open a score in MuseScore Studio 4.4.2 or later.

  2. Plugins > Manage plugins > enable MCP Score Bridge, then Plugins > MCP Score Bridge. Keep its window open.

  3. Ask your assistant to connect to MuseScore.

Details and troubleshooting: MuseScore plugin.

Documentation

Document

Description

Getting started

Set up mcp-score and generate your first score

Releases

What changed in each version

Tool reference

All MCP tools and CLI commands

MuseScore plugin

Plugin installation and WebSocket protocol

Architecture

System design and key decisions

Contributing

See CONTRIBUTING.md. Built in spare time, largely with Claude Code, and reviewed by a human before merge.

Author

Thomas Skovlund Hansen — skovlund.dev · thomas@skovlund.dev

License

MIT

Available Tools

23 tools
add_live_chord_symbolB

Add a chord symbol to a measure in the live score.

Args: measure: Measure number (1-indexed). symbol: Chord symbol (e.g. "Cmaj7", "Dm7", "G7").

Inputs: symbol (required), measure (required). Returns: result

add_live_dynamicA

Add a dynamic marking to a measure in the live score.

Args: measure: Measure number (1-indexed). dynamic: Dynamic such as "pp", "p", "mp", "mf", "f", "ff", "sfz". staff: Staff index (0-indexed, default: 0).

Inputs: dynamic (required), measure (required), staff. Returns: result

add_live_noteA

Add a note at the start of a measure in the live score.

Consecutive calls on the same measure append notes one after another, since the application advances its cursor after each note.

Args: measure: Measure number (1-indexed). pitch: MIDI pitch (60 = middle C). numerator: Duration numerator (default 1, with denominator 4 = quarter note). denominator: Duration denominator (default 4). staff: Staff index (0-indexed, default: 0).

Inputs: pitch (required), measure (required), staff, numerator, +1 more. Returns: result

add_live_rehearsal_markA

Add a rehearsal mark to a measure in the live score.

Args: measure: Measure number (1-indexed). text: Rehearsal mark text (e.g. "A", "B", "Intro").

Inputs: text (required), measure (required). Returns: result

append_live_measuresA

Append empty measures to the end of the live score.

Args: count: How many measures to append (default: 1).

Inputs: count. Returns: result

connect_to_doricoA

Connect to a running Dorico via its Remote Control API (experimental).

Dorico support is experimental: the Remote Control API is undocumented, command-only (it cannot read note content), and this bridge has not been verified against a running Dorico. Dorico 4 and later serve the API without a plugin; the port is set in Dorico's preferences. Connecting disconnects any other application.

Args: host: WebSocket host (default: localhost). port: WebSocket port (default: 4560, Dorico's default).

Inputs: host, port. Returns: result

connect_to_musescoreA

Connect to a running MuseScore Studio (4.4.2 or later).

The MCP Score Bridge plugin must be running in MuseScore with its window open. Connecting disconnects any other application.

Args: host: WebSocket host (default: localhost). port: WebSocket port (default: 8765).

Inputs: host, port. Returns: result

disconnect_from_doricoC

Disconnect from Dorico.

Inputs: no named parameters. Returns: result

disconnect_from_musescoreC

Disconnect from MuseScore.

Inputs: no named parameters. Returns: result

generate_scoreA

Run a music21 Python script to generate a score file (MusicXML).

Write a COMPLETE, self-contained music21 script that builds the whole score and ends by exporting it, e.g. score.write("musicxml", fp="My Piece.musicxml"). Use a plain file name (no directory) so the file lands in the working directory and is reported back in output_files. Read the score_generation_guide tool first: it holds the music21 conventions this project relies on (flats are written B- not Bb, metadata, repeats, volta brackets, transposing instruments, and a full template).

The script runs on the user's machine with the user's privileges, in the same Python interpreter as this server (so music21 is importable). Only send code the user would be comfortable running themselves.

Args: script: Complete Python source of the generation script. output_dir: Working directory for the run. Defaults to a fresh directory under the user's Desktop (or home directory when there is no Desktop). Created if it does not exist. timeout: Seconds to wait before killing the script (default: 120).

Returns: JSON. On success: {"success": true, "output_files": [absolute paths of files created in the working directory], "stdout": ...}. On failure: {"error": ..., "stderr": last lines, "returncode": n}.

Inputs: script (required), timeout, output_dir. Returns: result

get_live_score_infoA

Get information about the score open in the connected application.

Requires an active connection (connect_to_musescore or connect_to_dorico).

Inputs: no named parameters. Returns: result

get_measure_contentA

Select one measure of one staff in the live score and report it.

Args: measure: Measure number (1-indexed). staff: Staff index (0-indexed, default: 0).

Inputs: measure (required), staff. Returns: result

get_selection_propertiesA

Get properties of the current selection in the connected application.

MuseScore reports the cursor position (measure, beat, staff, element). Dorico reports the names, types and values of every property of the selected items, which is the closest its API gets to reading the score.

Inputs: no named parameters. Returns: result

ping_score_appA

Check whether the connected application responds. Does not connect.

Inputs: no named parameters. Returns: result

read_passageA

Read the content of a range of measures in the live score.

Returns what is at the cursor in each measure: notes, rests and other elements. MuseScore gives full note content; Dorico only reports its application status (see the warning in the result).

Args: start_measure: First measure to read (1-indexed). end_measure: Last measure to read (inclusive, 1-indexed). staff: Staff to read (0-indexed). Omit to read the current staff.

Inputs: end_measure (required), start_measure (required), staff. Returns: result

render_scoreA

Render a score file to PDF, PNG, MIDI, MP3, WAV or MusicXML.

Runs the MuseScore Studio 4 command line, so MuseScore Studio 4 must be installed. It does not need to be running, and no plugin or live connection is required. The input is typically a MusicXML file (.musicxml, .xml, .mxl) but can be any file MuseScore opens, such as .mscz or .mid.

MuseScore is located from the MCP_SCORE_MUSESCORE_PATH environment variable, then PATH (mscore, musescore, mscore4portable, MuseScore4), then the platform default install location (macOS app bundle, Windows Program Files, Linux Flatpak). If it is not found automatically, set MCP_SCORE_MUSESCORE_PATH to the executable in the MCP server's environment.

Args: input_path: Path to the score file to render. format: One of "pdf", "png", "midi", "mp3", "wav", "musicxml" (default: pdf). PNG export writes one file per page, named with a -1, -2, ... suffix before the extension. output_path: Where to write the result. Defaults to the input path with the format's extension. Its extension must match the format. An existing file is overwritten.

Inputs: input_path (required), format, output_path. Returns: result

score_generation_guideA

Return the score generation guide for writing music21 scripts.

Read this before calling generate_score. It is the bundled score-generate skill (instructions, music21 conventions and troubleshooting), the instrument class reference (which class to use for each instrument, with transposition handled by music21), and a complete runnable template script. Takes no parameters.

Returns the guide as Markdown, or {"error": ...} JSON if the bundled skill files cannot be found.

Inputs: no named parameters. Returns: result

set_live_barlineA

Set the bar line at the end of a measure in the live score.

Args: measure: Measure number (1-indexed). barline_type: One of "normal", "double", "final", "dashed", "dotted", "tick", "short", "startRepeat", "endRepeat" or "endStartRepeat". "startRepeat" marks the start of this measure; "endStartRepeat" ends a repeat here and starts one in the next measure.

Inputs: measure (required), barline_type (required). Returns: result

set_live_key_signatureA

Set the key signature from a measure onward in the live score.

Args: measure: Measure number (1-indexed). fifths: Sharps (positive) or flats (negative): 0 = C major, 2 = D major, -3 = Eb major.

Inputs: fifths (required), measure (required). Returns: result

set_live_tempoA

Set the tempo at a measure in the live score.

Args: measure: Measure number (1-indexed). bpm: Beats per minute. text: Optional display text (e.g. "Swing", "Allegro").

Inputs: bpm (required), measure (required), text. Returns: result

set_live_time_signatureA

Set the time signature from a measure onward in the live score.

Args: measure: Measure number (1-indexed). numerator: Beats per measure (e.g. 3 in 3/4). denominator: Beat unit (e.g. 4 in 3/4).

Inputs: measure (required), numerator (required), denominator (required). Returns: result

transpose_passageA

Transpose the notes of a passage by a number of semitones in the live score.

Notes are moved with conventional spelling (a minor second up turns C into Db). Key signatures and chord symbols in the passage are left unchanged.

Args: start_measure: First measure (1-indexed). end_measure: Last measure (inclusive, 1-indexed). staff: Staff index (0-indexed). semitones: Semitones to transpose (positive = up, negative = down).

Inputs: staff (required), semitones (required), end_measure (required), start_measure (required). Returns: result

undo_last_actionA

Undo the last change in the connected application.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (adding notes, chords, dynamics, etc.), but there is some overlap between get_measure_content and read_passage (both read score content), and between get_live_score_info and get_selection_properties (both report application state). Descriptions are detailed enough to clarify differences, so ambiguity is minimal.

    Naming Consistency4/5

    The majority of tools follow a verb_noun pattern (add_live_note, set_live_tempo, get_live_score_info), and many share a 'live' prefix for editing operations. Minor deviations like score_generation_guide (noun_noun) and render_score (verb_noun without 'live') are understandable but slightly break the pattern.

    Tool Count4/5

    With 23 tools, the server is on the higher end of typical MCP servers, but the scope is broad: live editing across two applications, file generation, rendering, and utility functions. Each tool serves a distinct function, so the count is justified, though a few could potentially be consolidated.

    Completeness4/5

    The tool surface covers core workflows: connecting, reading, adding elements, setting properties, transposing, undoing, generating scores, and rendering. Missing operations include deleting or modifying existing notes beyond transposition, but the undo tool mitigates some gaps. Overall, the surface is reasonably complete for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers