MuseScore MCP Server

Сервер протокола контекста модели (MCP), обеспечивающий программное управление MuseScore через систему плагинов на основе WebSocket. Это позволяет ИИ-ассистентам, таким как Claude, сочинять музыку, добавлять тексты песен, перемещаться по партитурам и управлять MuseScore напрямую.

Системные требования

• MuseScore 3.x или 4.x

• Python 3.8+

• Claude Desktop или совместимый MCP-клиент

Related MCP server: Ableton Copilot MCP

Установка

1. Установка плагина MuseScore

Сначала сохраните код QML-плагина в папку плагинов 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. Активация плагина в MuseScore

1. Откройте MuseScore

2. Перейдите в Плагины → Менеджер плагинов

3. Найдите "MuseScore API Server" и установите флажок, чтобы включить его

4. Нажмите OK

3. Настройка среды 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. Настройка Claude Desktop

Добавьте в файл конфигурации 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"
      ]
    }
  }
}

Примечание: Обновите пути в соответствии с фактическим расположением вашего проекта.

Запуск системы

Порядок действий

1. Сначала запустите MuseScore с открытой партитурой

2. Запустите плагин MuseScore: Перейдите в Плагины → MuseScore API Server

   • Вы должны увидеть вывод в консоли: "Starting MuseScore API Server on port 8765"

3. Затем запустите Python MCP-сервер или перезапустите Claude Desktop

[вставьте скриншот различного функционала, гармонизации, написания мелодии в виде анимированных GIF]

Разработка и тестирование

Для разработки используйте инструменты разработки MCP:

# Install MCP dev tools
pip install mcp

# Test your server
mcp dev server.py

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

Просмотр вывода консоли

Чтобы увидеть вывод консоли плагина MuseScore, запустите MuseScore из терминала:

macOS:

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

Windows:

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

Linux:

musescore4

Функции

Этот MCP-сервер предоставляет комплексное управление MuseScore.

🌟 НОВИНКА в этом форке: Встроенная автоматическая, безупречная многоголосная полифония и отображение временной разметки в LilyPond!

Навигация и управление курсором

• get_cursor_info() - Получить информацию о текущей позиции курсора и выделении

• go_to_measure(measure) - Перейти к определенному такту

• go_to_beginning_of_score() / go_to_final_measure() - Перейти к началу/концу

• next_element() / prev_element() - Переместить курсор по элементам

• next_staff() / prev_staff() - Перемещаться между нотоносцами

• select_current_measure() - Выделить весь текущий такт

• select_custom_range(start_tick, end_tick, start_staff, end_staff) - Инструмент выделения для извлечения фраз, охватывающих несколько тактов и нотоносцев

Полифония и интеграция с LilyPond

• Временное заполнение ритма: Голоса с пропусками или паузами автоматически получают последовательности заполнителей LilyPond (s4.) для точного сохранения их математического места.

• Параллельный рендеринг голосов: Полные 4-голосные массивы (\voiceOne, \voiceTwo и т.д.), правильно структурированные и разделенные по нотоносцам для продвинутой обработки агентом.

Создание нот и пауз

• add_note(pitch, duration, advance_cursor_after_action) - Добавить ноты с использованием MIDI-высоты тона

• add_rest(duration, advance_cursor_after_action) - Добавить паузы

• add_tuplet(duration, ratio, advance_cursor_after_action) - Добавить туоли (триоли и т.д.)

Управление тактами

• insert_measure() - Вставить такт в текущую позицию

• append_measure(count) - Добавить такты в конец партитуры

• delete_selection(measure) - Удалить текущее выделение или конкретный такт

Тексты песен и текст

• add_lyrics_to_current_note(text) - Добавить текст к текущей ноте

• add_lyrics(lyrics_list) - Пакетное добавление текста к нескольким нотам

• set_title(title) - Установить название партитуры

Информация о партитуре

• get_score() - Получить полный анализ и структуру партитуры

• ping_musescore() - Проверить соединение с MuseScore

• connect_to_musescore() - Установить WebSocket-соединение

Утилиты

• undo() - Отменить последнее действие

• set_time_signature(numerator, denominator) - Изменить размер

• processSequence(sequence) - Выполнить несколько команд пакетом

Примеры музыки

Ознакомьтесь с папкой /examples для получения примеров файлов MuseScore, демонстрирующих различные музыкальные стили:

• Asian Instrumental - Традиционное инструментальное произведение в азиатском стиле

• String Quartet - Аранжировка для струнного квартета

Каждый пример включает:

• .mscz - Файл MuseScore (редактируемый)

• .pdf - Ноты

• .mp3 - Аудио-превью

Примеры использования

Создание простой мелодии

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

Пакетные операции

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

История звезд

Устранение неполадок

Проблемы с подключением

• "Not connected to MuseScore":

  • Убедитесь, что MuseScore запущен и открыта партитура

  • Запустите плагин MuseScore (Plugins → MuseScore API Server)

  • Проверьте, что порт 8765 не заблокирован брандмауэром

Проблемы с плагином

• Плагин не отображается: Проверьте, находится ли файл .qml в правильной папке плагинов

• Плагин не включается: Перезапустите MuseScore после размещения файла плагина

• Нет вывода в консоли: Запустите MuseScore из терминала, чтобы увидеть отладочные сообщения

Проблемы с Python-сервером

• "No server object found": Объект сервера должен называться mcp, server или app на уровне модуля

• Ошибки WebSocket: Убедитесь, что плагин MuseScore запущен перед запуском Python-сервера

• Тайм-аут соединения: Плагин MuseScore должен быть активно запущен, а не просто включен

Ограничения API

• Тексты песен: В API плагина MuseScore 3.x поддерживается только первый куплет

• Установка заголовка: Использует несколько резервных методов из-за ограничений доступа к фреймам

• Сохранение выделения: Некоторые операции могут влиять на текущее выделение

Структура файлов

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-высоты тона

Общие значения MIDI-высоты тона для справки:

• До первой октавы (Middle C): 60

• Гамма До мажор: 60, 62, 64, 65, 67, 69, 71, 72

• Хроматическая: C=60, C#=61, D=62, D#=63, E=64, F=65, F#=66, G=67, G#=68, A=69, A#=70, B=71

Справочник длительностей

Формат длительности: {"numerator": int, "denominator": int}

• Целая нота: {"numerator": 1, "denominator": 1}

• Половинная нота: {"numerator": 1, "denominator": 2}

• Четвертная нота: {"numerator": 1, "denominator": 4}

• Восьмая нота: {"numerator": 1, "denominator": 8}

• Четверть с точкой: {"numerator": 3, "denominator": 8}