MuseScore MCP Server

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.

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

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

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:

Viewing Console Output

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

macOS:

Windows:

Linux:

Features

This MCP server provides comprehensive MuseScore control:

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

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

Batch Operations

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

Requirements

Create a requirements.txt file with:

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}