MuseScore MCP Server

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

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

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.

🌟 NEW in this fork: Built-in automatic, flawless multi-voice Polyphony & Temporal layout mapping to LilyPond!

Navigation & Cursor 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
• select_custom_range(start_tick, end_tick, start_staff, end_staff) - Slicing tool to extract cross-measure, multi-staff phrasing

Polyphony & LilyPond Integration

• Temporal Rhythm Padding: Voices with gaps or rests automatically receive LilyPond spacer sequences (s4.) to hold their mathematical place accurately.
• Concurrent Voice Rendering: Full 4-voice (\voiceOne, \voiceTwo, etc.) arrays correctly structured and sharded per staff for advanced Agent processing.

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 positi

... View full README on GitHub