You can control MuseScore programmatically through a WebSocket-based MCP server, enabling AI assistants to compose music, add lyrics, navigate scores, and manage score content with scripted commands.

How to use

You will use an MCP client to send commands to the MuseScore MCP server. Start MuseScore with a score open, ensure the MuseScore API Server plugin is active, and then connect your MCP client to the server. Use the available navigation, note editing, lyric, and score management actions to perform tasks like moving the cursor, inserting notes, adding lyrics, and changing score properties.

How to install

Prerequisites: MuseScore 3.x or 4.x, Python 3.8 or newer, and a compatible MCP client such as Claude Desktop.

# 1. Install the MuseScore Plugin
# 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
# Open MuseScore, then go to Plugins → Plugin Manager
# Find "MuseScore API Server" and enable it, then click OK

# 3. Setup Python Environment

# Clone your project, create a virtual environment, and install dependencies

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 (example)
# 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

Follow this exact flow to start and test the system. Begin with MuseScore running a score, then start the MuseScore API Server plugin, and finally start the MCP server.

1) Start MuseScore with a score open. 2) Run the MuseScore API Server plugin from MuseScore: Plugins → MuseScore API Server. You should see console output indicating the server is starting on a specific port, such as "Starting MuseScore API Server on port 8765". 3) Start the Python MCP server or restart your client application after the plugin is running.

## Development and Testing

For development, install MCP development tools and test your server locally.

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, launch MuseScore from the terminal.

macOS

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

Windows

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

Linux

musescore4

## Available tools

### get\_cursor\_info

Retrieve the current cursor position and selection details in the active score.

### go\_to\_measure

Navigate the score to a specific measure number.

### go\_to\_beginning\_of\_score

Move the cursor to the beginning of the score.

### go\_to\_final\_measure

Move the cursor to the final measure of the score.

### next\_element

Advance the cursor to the next musical element.

### prev\_element

Move the cursor to the previous musical element.

### next\_staff

Move the cursor to the next staff.

### prev\_staff

Move the cursor to the previous staff.

### select\_current\_measure

Select the entire measure where the cursor currently sits.

### add\_note

Insert a note by MIDI pitch with a given duration and optional cursor advancement.

### add\_rest

Insert a rest with a given duration and optional cursor advancement.

### add\_tuplet

Insert a tuplet with a specified duration and ratio (e.g., triplets).

### insert\_measure

Insert a new measure at the current position.

### append\_measure

Append a number of measures to the end of the score.

### delete\_selection

Delete the currently selected measure or selection.

### add\_lyrics\_to\_current\_note

Attach lyrics to the note currently under the cursor.

### add\_lyrics

Batch add lyrics to a sequence of notes.

### set\_title

Set the title of the score.

### get\_score

Retrieve a complete analysis and structure of the current score.

### ping\_musescore

Test the connection to the MuseScore plugin server.

### connect\_to\_musescore

Establish the WebSocket connection to MuseScore.

### undo

Undo the last action.

### set\_time\_signature

Change the time signature using a numerator and denominator.

### processSequence

Execute a batch of actions in sequence.