Servidor MCP de MuseScore

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona control programático sobre MuseScore a través de un sistema de complementos basado en WebSocket. Esto permite a los asistentes de IA como Claude componer música, añadir letras, navegar por partituras y controlar MuseScore directamente.

Requisitos previos

• MuseScore 3.x o 4.x

• Python 3.8+

• Claude Desktop o un cliente MCP compatible

Related MCP server: Ableton Copilot MCP

Configuración

1. Instalar el complemento de MuseScore

Primero, guarda el código del complemento QML en tu directorio de complementos de MuseScore:

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. Habilitar el complemento en MuseScore

1. Abre MuseScore

2. Ve a Plugins → Gestor de plugins

3. Busca "MuseScore API Server" y marca la casilla para habilitarlo

4. Haz clic en OK

3. Configurar el entorno de Python

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. Configurar Claude Desktop

Añade esto a tu archivo de configuración de Claude Desktop:

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

Nota: Actualiza las rutas para que coincidan con la ubicación real de tu proyecto.

Ejecución del sistema

Orden de operaciones

1. Inicia MuseScore primero con una partitura abierta

2. Ejecuta el complemento de MuseScore: Ve a Plugins → MuseScore API Server

   • Deberías ver la salida de la consola: "Starting MuseScore API Server on port 8765"

3. Luego inicia el servidor MCP de Python o reinicia Claude Desktop

[insertar captura de pantalla de diferentes funcionalidades, armonización, escritura de melodías, como GIFs con zoom]

Desarrollo y pruebas

Para el desarrollo, utiliza las herramientas de desarrollo de MCP:

# Install MCP dev tools
pip install mcp

# Test your server
mcp dev server.py

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

Ver la salida de la consola

Para ver la salida de la consola del complemento de MuseScore, ejecuta MuseScore desde la terminal:

macOS:

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

Windows:

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

Linux:

musescore4

Características

Este servidor MCP proporciona un control integral de MuseScore.

🌟 NUEVO en esta bifurcación: ¡Polifonía multipista automática e impecable y mapeo de diseño temporal a LilyPond!

Navegación y control del cursor

• get_cursor_info() - Obtiene la posición actual del cursor y la información de selección

• go_to_measure(measure) - Navega a un compás específico

• go_to_beginning_of_score() / go_to_final_measure() - Navega al inicio/final

• next_element() / prev_element() - Mueve el cursor elemento por elemento

• next_staff() / prev_staff() - Mueve entre pentagramas

• select_current_measure() - Selecciona todo el compás actual

• select_custom_range(start_tick, end_tick, start_staff, end_staff) - Herramienta de corte para extraer frases que abarcan varios compases y pentagramas

Integración de polifonía y LilyPond

• Relleno de ritmo temporal: Las voces con espacios o silencios reciben automáticamente secuencias de espaciado de LilyPond (s4.) para mantener su lugar matemático con precisión.

• Renderizado de voz concurrente: Matrices completas de 4 voces (\voiceOne, \voiceTwo, etc.) estructuradas correctamente y fragmentadas por pentagrama para un procesamiento avanzado por parte del Agente.

Creación de notas y silencios

• add_note(pitch, duration, advance_cursor_after_action) - Añade notas con tono MIDI

• add_rest(duration, advance_cursor_after_action) - Añade silencios

• add_tuplet(duration, ratio, advance_cursor_after_action) - Añade tresillos (u otros grupos de valoración especial)

Gestión de compases

• insert_measure() - Inserta un compás en la posición actual

• append_measure(count) - Añade compases al final de la partitura

• delete_selection(measure) - Elimina la selección actual o un compás específico

Letras y texto

• add_lyrics_to_current_note(text) - Añade letras a la nota actual

• add_lyrics(lyrics_list) - Añade letras por lotes a varias notas

• set_title(title) - Establece el título de la partitura

Información de la partitura

• get_score() - Obtiene el análisis y la estructura completa de la partitura

• ping_musescore() - Prueba la conexión con MuseScore

• connect_to_musescore() - Establece la conexión WebSocket

Utilidades

• undo() - Deshace la última acción

• set_time_signature(numerator, denominator) - Cambia el compás

• processSequence(sequence) - Ejecuta múltiples comandos por lotes

Música de muestra

Consulta la carpeta /examples para ver archivos de MuseScore de muestra que demuestran varios estilos musicales:

• Asian Instrumental - Pieza instrumental tradicional de inspiración asiática

• String Quartet - Arreglo clásico para cuarteto de cuerda

Cada ejemplo incluye:

• .mscz - Archivo de MuseScore (editable)

• .pdf - Partitura

• .mp3 - Vista previa de audio

Ejemplos de uso

Crear una melodía simple

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

Operaciones por lotes

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

Historial de estrellas

Solución de problemas

Problemas de conexión

• "Not connected to MuseScore":

  • Asegúrate de que MuseScore se esté ejecutando con una partitura abierta

  • Ejecuta el complemento de MuseScore (Plugins → MuseScore API Server)

  • Comprueba que el puerto 8765 no esté bloqueado por el firewall

Problemas con el complemento

• El complemento no aparece: Comprueba que el archivo .qml esté en el directorio de complementos correcto

• El complemento no se habilita: Reinicia MuseScore después de colocar el archivo del complemento

• Sin salida de consola: Ejecuta MuseScore desde la terminal para ver los mensajes de depuración

Problemas con el servidor de Python

• "No server object found": El objeto del servidor debe llamarse mcp, server o app a nivel de módulo

• Errores de WebSocket: Asegúrate de que el complemento de MuseScore se esté ejecutando antes de iniciar el servidor de Python

• Tiempo de espera de conexión: El complemento de MuseScore debe estar ejecutándose activamente, no solo habilitado

Limitaciones de la API

• Letras: Solo se admite la primera estrofa en la API del complemento de MuseScore 3.x

• Configuración del título: Utiliza múltiples métodos de respaldo debido a las limitaciones de acceso a los marcos

• Persistencia de la selección: Algunas operaciones pueden afectar a la selección actual

Estructura de archivos

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

Referencia de tono MIDI

Valores de tono MIDI comunes como referencia:

• Do central: 60

• Escala de Do Mayor: 60, 62, 64, 65, 67, 69, 71, 72

• Cromática: Do=60, Do#=61, Re=62, Re#=63, Mi=64, Fa=65, Fa#=66, Sol=67, Sol#=68, La=69, La#=70, Si=71

Referencia de duración

Formato de duración: {"numerator": int, "denominator": int}

• Redonda: {"numerator": 1, "denominator": 1}

• Blanca: {"numerator": 1, "denominator": 2}

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

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

• Negra con puntillo: {"numerator": 3, "denominator": 8}