mcp-musescore

This MuseScore MCP server exposes a WebSocket-based API to control MuseScore from AI agents via a MuseScore plugin. The plugin runs inside MuseScore and opens a WebSocket connection to the Python MCP server, allowing programmatic navigation, note and rest creation, lyrics handling, score information, and utility operations. Tools implemented cover navigation (cursor movement, going to measures or scores, and moving between staves), note and rest creation (adding notes and rests with MIDI pitches and durations), measure management (insert, append, delete), lyrics and text editing, score metadata, and batch/sequence processing for complex operations. With this setup, an agent can compose music, add lyrics, adjust tempo or time signature, and retrieve score structure all through the MCP protocol.

To use it, ensure MuseScore is running with a score open and that the MuseScore API Server plugin is enabled in Plugins → Plugin Manager. Start the Python MCP server (e.g., python server.py) so the MCP server can establish a WebSocket connection to MuseScore via the plugin. Clients ( Claude Desktop or any MCP client) can then issue commands like add_note, set_title, get_score, or processSequence to perform rich musical edits in real time. The configuration in Claude Desktop points to your local MCP server entry point, enabling seamless integration into your assistant workflows.

Prerequisites:

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

Step-by-step installation:

1. Install MuseScore and verify the plugin location

• Save the MuseScore MCP WebSocket plugin (musescore-mcp-websocket.qml) in your MuseScore plugins directory.
• macOS: ~/Documents/MuseScore4/Plugins/
• Windows: %USERPROFILE%\Documents\MuseScore4\Plugins\
• Linux: ~/Documents/MuseScore4/Plugins/

2. Prepare the Python MCP server environment

• Clone the repository containing the MCP server:

git clone <your-repo>
cd mcp-musescore

• Create a virtual environment and activate it:

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.
venv\Scripts\activate

• Install dependencies:

pip install -r requirements.txt

3. Run the server and MuseScore plugin

• Start MuseScore first, with a score open, and ensure the MuseScore API Server plugin is enabled.
• Run the MCP server:

python server.py

• The server should connect to MuseScore via the plugin (look for connection messages in MuseScore plugin console and server logs).

4. Configure Claude/Desktop MCP client

• In Claude Desktop, point the mcpServers configuration to the local Python server entry, similar to:

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

5. Verify the connection

• Start MuseScore first, then start the Python MCP server, and finally launch Claude Desktop or your MCP client to interact with the server. If the connection succeeds, you should see logs indicating the MuseScore API Server is running and a client connection is established.

Tips and known considerations:

• Port: The MuseScore API Server plugin typically listens on port 8765; ensure this port is not blocked by your firewall.
• Plugin readiness: The MuseScore plugin must be running and connected before issuing MCP commands.
• Environment variables: If using a virtual environment, activate it before starting the MCP server or point the Python command to the virtual environment’s interpreter.
• Dependencies: The repository includes a requirements.txt; install with pip install -r requirements.txt.
• Sample commands: Use get_score(), add_note(), add_lyrics_to_current_note(), set_title(), and processSequence() to perform common tasks.
• Troubleshooting: If you see “Not connected to MuseScore” or “No server object found,” ensure the plugin is loaded in MuseScore and that the server module exposes the correct entry point names (e.g., mcp, server, or app) at the module level.