Skip to main content
Glama

MuseScore MCP Server

by ghchen99
MIT License
2
  • Apple
  • Linux

MuseScore MCP Server

A Model Context Protocol (MCP) server that provides programmatic control over MuseScore through a WebSocket-based plugin system. This allows AI assistants like Claude to compose music, add lyrics, navigate scores, and control MuseScore directly.

Demo GIF

Prerequisites

  • MuseScore 3.x or 4.x
  • Python 3.8+
  • Claude Desktop or compatible MCP client

Setup

1. Install the MuseScore Plugin

First, save the QML plugin code to your MuseScore plugins directory:

macOS: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml Windows: %USERPROFILE%\Documents\MuseScore4\Plugins\musescore-mcp-websocket.qml Linux: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml

2. Enable the Plugin in MuseScore

  1. Open MuseScore
  2. Go to Plugins → Plugin Manager
  3. Find "MuseScore API Server" and check the box to enable it
  4. Click OK

3. Setup Python Environment

git clone <your-repo> cd mcp-agents-demo python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install fastmcp websockets

4. Configure Claude Desktop

Add to your Claude Desktop configuration file:

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

{ "mcpServers": { "musescore": { "command": "/path/to/your/project/.venv/bin/python", "args": [ "/path/to/your/project/server.py" ] } } }

Note: Update the paths to match your actual project location.

Running the System

Order of Operations (Important!)

  1. Start MuseScore first with a score open
  2. Run the MuseScore plugin: Go to Plugins → MuseScore API Server
    • You should see console output: "Starting MuseScore API Server on port 8765"
  3. Then start the Python MCP server or restart Claude Desktop

[insert screenshot of different functionality, harmonisation, melodywriting, as zoomed in GIFs]

Development and Testing

For development, use the MCP development tools:

# Install MCP dev tools pip install mcp # Test your server mcp dev server.py # Check connection status mcp dev server.py --inspect

Viewing Console Output

To see MuseScore plugin console output, run MuseScore from terminal:

macOS:

/Applications/MuseScore\ 4.app/Contents/MacOS/mscore

Windows:

cd "C:\Program Files\MuseScore 4\bin" MuseScore.exe

Linux:

musescore4

Features

This MCP server provides comprehensive MuseScore control:

  • get_cursor_info() - Get current cursor position and selection info
  • go_to_measure(measure) - Navigate to specific measure
  • go_to_beginning_of_score() / go_to_final_measure() - Navigate to start/end
  • next_element() / prev_element() - Move cursor element by element
  • next_staff() / prev_staff() - Move between staves
  • select_current_measure() - Select entire current measure

Note & Rest Creation

  • add_note(pitch, duration, advance_cursor_after_action) - Add notes with MIDI pitch
  • add_rest(duration, advance_cursor_after_action) - Add rests
  • add_tuplet(duration, ratio, advance_cursor_after_action) - Add tuplets (triplets, etc.)

Measure Management

  • insert_measure() - Insert measure at current position
  • append_measure(count) - Add measures to end of score
  • delete_selection(measure) - Delete current selection or specific measure

Lyrics & Text

  • add_lyrics_to_current_note(text) - Add lyrics to current note
  • add_lyrics(lyrics_list) - Batch add lyrics to multiple notes
  • set_title(title) - Set score title

Score Information

  • get_score() - Get complete score analysis and structure
  • ping_musescore() - Test connection to MuseScore
  • connect_to_musescore() - Establish WebSocket connection

Utilities

  • undo() - Undo last action
  • set_time_signature(numerator, denominator) - Change time signature
  • processSequence(sequence) - Execute multiple commands in batch

Sample Music

Check out the /examples folder for sample MuseScore files demonstrating various musical styles:

  • Asian Instrumental - Traditional Asian-inspired instrumental piece
  • String Quartet - Classical string quartet arrangement

Each example includes:

  • .mscz - MuseScore file (editable)
  • .pdf - Sheet music
  • .mp3 - Audio preview

Usage Examples

Creating a Simple Melody

# Set up the score await set_title("My First Song") await go_to_beginning_of_score() # Add notes (MIDI pitch: 60=C, 62=D, 64=E, etc.) await add_note(60, {"numerator": 1, "denominator": 4}, True) # Quarter note C await add_note(64, {"numerator": 1, "denominator": 4}, True) # Quarter note E await add_note(67, {"numerator": 1, "denominator": 4}, True) # Quarter note G await add_note(72, {"numerator": 1, "denominator": 2}, True) # Half note C # Add lyrics await go_to_beginning_of_score() await add_lyrics_to_current_note("Do") await next_element() await add_lyrics_to_current_note("Mi") await next_element() await add_lyrics_to_current_note("Sol") await next_element() await add_lyrics_to_current_note("Do")

Batch Operations

# Add multiple lyrics at once await add_lyrics(["Twin-", "kle", "twin-", "kle", "lit-", "tle", "star"]) # Use sequence processing for complex operations sequence = [ {"action": "goToBeginningOfScore", "params": {}}, {"action": "addNote", "params": {"pitch": 60, "duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}}, {"action": "addNote", "params": {"pitch": 64, "duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}}, {"action": "addRest", "params": {"duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}} ] await processSequence(sequence)

Troubleshooting

Connection Issues

  • "Not connected to MuseScore":
    • Ensure MuseScore is running with a score open
    • Run the MuseScore plugin (Plugins → MuseScore API Server)
    • Check that port 8765 isn't blocked by firewall

Plugin Issues

  • Plugin not appearing: Check the .qml file is in the correct plugins directory
  • Plugin won't enable: Restart MuseScore after placing the plugin file
  • No console output: Run MuseScore from terminal to see debug messages

Python Server Issues

  • "No server object found": The server object must be named mcp, server, or app at module level
  • WebSocket errors: Make sure MuseScore plugin is running before starting Python server
  • Connection timeout: The MuseScore plugin must be actively running, not just enabled

API Limitations

  • Lyrics: Only first verse supported in MuseScore 3.x plugin API
  • Title setting: Uses multiple fallback methods due to frame access limitations
  • Selection persistence: Some operations may affect current selection

File Structure

mcp-agents-demo/ ├── .venv/ ├── server.py # Python MCP server entry point ├── musescore-mcp-websocket.qml # MuseScore plugin ├── requirements.txt ├── README.md └── src/ # Source code modules ├── __init__.py ├── client/ # WebSocket client functionality │ ├── __init__.py │ └── websocket_client.py ├── tools/ # MCP tool implementations │ ├── __init__.py │ ├── connection.py # Connection management tools │ ├── navigation.py # Score navigation tools │ ├── notes_measures.py # Note and measure manipulation │ ├── sequences.py # Batch operation tools │ ├── staff_instruments.py # Staff and instrument tools │ └── time_tempo.py # Timing and tempo tools └── types/ # Type definitions ├── __init__.py └── action_types.py # WebSocket action type definitions

Requirements

Create a requirements.txt file with:

fastmcp websockets

MIDI Pitch Reference

Common MIDI pitch values for reference:

  • Middle C: 60
  • C Major Scale: 60, 62, 64, 65, 67, 69, 71, 72
  • Chromatic: C=60, C#=61, D=62, D#=63, E=64, F=65, F#=66, G=67, G#=68, A=69, A#=70, B=71

Duration Reference

Duration format: {"numerator": int, "denominator": int}

  • Whole note: {"numerator": 1, "denominator": 1}
  • Half note: {"numerator": 1, "denominator": 2}
  • Quarter note: {"numerator": 1, "denominator": 4}
  • Eighth note: {"numerator": 1, "denominator": 8}
  • Dotted quarter: {"numerator": 3, "denominator": 8}

Related MCP Servers

  • A
    security
    F
    license
    A
    quality
    A lightweight Model Context Protocol server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.
    Last updated -
    12
    80
    TypeScript
  • -
    security
    A
    license
    -
    quality
    A Model Context Protocol server that allows AI assistants like Claude and Cursor to create music and control Sonic Pi programmatically through OSC messages.
    Last updated -
    10
    7
    TypeScript
    MIT License
  • -
    security
    F
    license
    -
    quality
    A Model Context Protocol server that enables AI assistants like Claude to interact with Spotify, allowing them to search for tracks, control playback, and manage playlists.
    Last updated -
    1
    TypeScript
    • Apple
  • -
    security
    A
    license
    -
    quality
    A Model Context Protocol server that enables AI assistants like Claude to generate lyrics, songs, and background music through Mureka's APIs.
    Last updated -
    12
    Python
    MIT License
    • Apple

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ghchen99/mcp-musescore'

If you have feedback or need assistance with the MCP directory API, please join our Discord server