MuseScore MCP-Server

Ein Model Context Protocol (MCP)-Server, der eine programmgesteuerte Kontrolle über MuseScore durch ein WebSocket-basiertes Plugin-System ermöglicht. Dies erlaubt KI-Assistenten wie Claude, Musik zu komponieren, Liedtexte hinzuzufügen, durch Partituren zu navigieren und MuseScore direkt zu steuern.

Voraussetzungen

• MuseScore 3.x oder 4.x

• Python 3.8+

• Claude Desktop oder ein kompatibler MCP-Client

Related MCP server: Mureka MCP Server

Einrichtung

1. Installieren des MuseScore-Plugins

Speichern Sie zuerst den QML-Plugin-Code in Ihrem MuseScore-Plugin-Verzeichnis:

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. Aktivieren des Plugins in MuseScore

1. Öffnen Sie MuseScore

2. Gehen Sie zu Plugins → Plugin-Manager

3. Suchen Sie "MuseScore API Server" und aktivieren Sie das Kontrollkästchen

4. Klicken Sie auf OK

3. Einrichten der Python-Umgebung

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. Konfigurieren von Claude Desktop

Fügen Sie dies Ihrer Claude Desktop-Konfigurationsdatei hinzu:

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"
      ]
    }
  }
}

Hinweis: Aktualisieren Sie die Pfade, damit sie Ihrem tatsächlichen Projektstandort entsprechen.

Ausführen des Systems

Reihenfolge der Vorgänge

1. Starten Sie zuerst MuseScore mit einer geöffneten Partitur

2. Starten Sie das MuseScore-Plugin: Gehen Sie zu Plugins → MuseScore API Server

   • Sie sollten eine Konsolenausgabe sehen: "Starting MuseScore API Server on port 8765"

3. Starten Sie dann den Python MCP-Server oder starten Sie Claude Desktop neu

[Fügen Sie hier Screenshots verschiedener Funktionen ein, wie Harmonisierung, Melodieschreiben, als gezoomte GIFs]

Entwicklung und Tests

Verwenden Sie für die Entwicklung die MCP-Entwicklungstools:

# Install MCP dev tools
pip install mcp

# Test your server
mcp dev server.py

# Check connection status
mcp dev server.py --inspect

Anzeigen der Konsolenausgabe

Um die Konsolenausgabe des MuseScore-Plugins zu sehen, starten Sie MuseScore über das Terminal:

macOS:

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

Windows:

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

Linux:

musescore4

Funktionen

Dieser MCP-Server bietet eine umfassende Steuerung von MuseScore.

🌟 NEU in diesem Fork: Integrierte automatische, fehlerfreie mehrstimmige Polyphonie & temporales Layout-Mapping zu LilyPond!

Navigation & Cursor-Steuerung

• get_cursor_info() - Aktuelle Cursorposition und Auswahl-Informationen abrufen

• go_to_measure(measure) - Zu einem bestimmten Takt navigieren

• go_to_beginning_of_score() / go_to_final_measure() - Zum Anfang/Ende navigieren

• next_element() / prev_element() - Cursor Element für Element bewegen

• next_staff() / prev_staff() - Zwischen Notensystemen wechseln

• select_current_measure() - Den gesamten aktuellen Takt auswählen

• select_custom_range(start_tick, end_tick, start_staff, end_staff) - Werkzeug zum Extrahieren von Phrasierungen über Takte und Notensysteme hinweg

Polyphonie & LilyPond-Integration

• Temporales Rhythmus-Padding: Stimmen mit Lücken oder Pausen erhalten automatisch LilyPond-Platzhaltersequenzen (s4.), um ihren mathematischen Platz präzise zu halten.

• Gleichzeitiges Stimmen-Rendering: Vollständige 4-stimmige (\voiceOne, \voiceTwo usw.) Arrays, die korrekt strukturiert und pro Notensystem für die erweiterte Agentenverarbeitung aufgeteilt sind.

Erstellen von Noten & Pausen

• add_note(pitch, duration, advance_cursor_after_action) - Noten mit MIDI-Tonhöhe hinzufügen

• add_rest(duration, advance_cursor_after_action) - Pausen hinzufügen

• add_tuplet(duration, ratio, advance_cursor_after_action) - Triolen/N-tolen hinzufügen

Taktverwaltung

• insert_measure() - Takt an der aktuellen Position einfügen

• append_measure(count) - Takte am Ende der Partitur anhängen

• delete_selection(measure) - Aktuelle Auswahl oder bestimmten Takt löschen

Liedtexte & Text

• add_lyrics_to_current_note(text) - Liedtext zur aktuellen Note hinzufügen

• add_lyrics(lyrics_list) - Liedtexte stapelweise zu mehreren Noten hinzufügen

• set_title(title) - Titel der Partitur festlegen

Partitur-Informationen

• get_score() - Vollständige Partituranalyse und -struktur abrufen

• ping_musescore() - Verbindung zu MuseScore testen

• connect_to_musescore() - WebSocket-Verbindung herstellen

Dienstprogramme

• undo() - Letzte Aktion rückgängig machen

• set_time_signature(numerator, denominator) - Taktart ändern

• processSequence(sequence) - Mehrere Befehle stapelweise ausführen

Musikbeispiele

Schauen Sie im Ordner /examples nach MuseScore-Beispieldateien, die verschiedene Musikstile demonstrieren:

• Asian Instrumental - Traditionelles, asiatisch inspiriertes Instrumentalstück

• String Quartet - Klassisches Streichquartett-Arrangement

Jedes Beispiel enthält:

• .mscz - MuseScore-Datei (bearbeitbar)

• .pdf - Notenblatt

• .mp3 - Audio-Vorschau

Anwendungsbeispiele

Erstellen einer einfachen Melodie

# 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")

Stapelverarbeitung

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

Star-Verlauf

Fehlerbehebung

Verbindungsprobleme

• "Not connected to MuseScore":

  • Stellen Sie sicher, dass MuseScore mit einer geöffneten Partitur läuft

  • Führen Sie das MuseScore-Plugin aus (Plugins → MuseScore API Server)

  • Überprüfen Sie, ob Port 8765 nicht durch eine Firewall blockiert wird

Plugin-Probleme

• Plugin erscheint nicht: Überprüfen Sie, ob sich die .qml-Datei im richtigen Plugin-Verzeichnis befindet

• Plugin lässt sich nicht aktivieren: Starten Sie MuseScore neu, nachdem Sie die Plugin-Datei platziert haben

• Keine Konsolenausgabe: Starten Sie MuseScore über das Terminal, um Debug-Meldungen zu sehen

Python-Server-Probleme

• "No server object found": Das Server-Objekt muss auf Modulebene mcp, server oder app heißen

• WebSocket-Fehler: Stellen Sie sicher, dass das MuseScore-Plugin läuft, bevor Sie den Python-Server starten

• Verbindungs-Timeout: Das MuseScore-Plugin muss aktiv laufen, nicht nur aktiviert sein

API-Einschränkungen

• Liedtexte: Nur die erste Strophe wird in der MuseScore 3.x Plugin-API unterstützt

• Titel-Einstellung: Verwendet aufgrund von Frame-Zugriffsbeschränkungen mehrere Fallback-Methoden

• Auswahl-Persistenz: Einige Vorgänge können die aktuelle Auswahl beeinflussen

Dateistruktur

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

MIDI-Tonhöhenreferenz

Allgemeine MIDI-Tonhöhenwerte als Referenz:

• Eingestrichenes C (Middle C): 60

• C-Dur-Tonleiter: 60, 62, 64, 65, 67, 69, 71, 72

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

Dauer-Referenz

Dauerformat: {"numerator": int, "denominator": int}

• Ganze Note: {"numerator": 1, "denominator": 1}

• Halbe Note: {"numerator": 1, "denominator": 2}

• Viertelnote: {"numerator": 1, "denominator": 4}

• Achtelnote: {"numerator": 1, "denominator": 8}

• Punktierte Viertelnote: {"numerator": 3, "denominator": 8}