MuseScore MCP 서버

WebSocket 기반 플러그인 시스템을 통해 MuseScore를 프로그래밍 방식으로 제어할 수 있는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이를 통해 Claude와 같은 AI 어시스턴트가 직접 음악을 작곡하고, 가사를 추가하며, 악보를 탐색하고 MuseScore를 제어할 수 있습니다.

사전 요구 사항

• MuseScore 3.x 또는 4.x

• Python 3.8+

• Claude Desktop 또는 호환되는 MCP 클라이언트

Related MCP server: Mureka MCP Server

설정

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. **플러그인(Plugins) → 플러그인 관리자(Plugin Manager)**로 이동

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 플러그인 실행: 플러그인(Plugins) → 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를 위한 자동화된 완벽한 다성부(Polyphony) 및 시간적 레이아웃 매핑!

탐색 및 커서 제어

• 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) - 마디를 가로지르는 다중 오선 프레이징 추출을 위한 슬라이싱 도구

다성부(Polyphony) 및 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) - 여러 명령을 일괄 실행

샘플 음악

다양한 음악 스타일을 보여주는 샘플 MuseScore 파일은 /examples 폴더를 확인하세요:

• Asian Instrumental - 전통 아시아풍 악기 연주곡

• String Quartet - 클래식 현악 4중주 편곡

각 예제 포함 항목:

• .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)

Star History

문제 해결

연결 문제

• "Not connected to MuseScore":

  • MuseScore가 실행 중이고 악보가 열려 있는지 확인하세요.

  • MuseScore 플러그인을 실행하세요 (플러그인 → MuseScore API Server).

  • 8765 포트가 방화벽에 의해 차단되지 않았는지 확인하세요.

플러그인 문제

• 플러그인이 나타나지 않음: .qml 파일이 올바른 플러그인 디렉토리에 있는지 확인하세요.

• 플러그인이 활성화되지 않음: 플러그인 파일을 넣은 후 MuseScore를 재시작하세요.

• 콘솔 출력 없음: 터미널에서 MuseScore를 실행하여 디버그 메시지를 확인하세요.

Python 서버 문제

• "No server object found": 서버 객체는 모듈 수준에서 mcp, server 또는 app으로 명명되어야 합니다.

• WebSocket 오류: Python 서버를 시작하기 전에 MuseScore 플러그인이 실행 중인지 확인하세요.

• 연결 시간 초과: MuseScore 플러그인은 단순히 활성화된 상태가 아니라 실제로 실행 중이어야 합니다.

API 제한 사항

• 가사: MuseScore 3.x 플러그인 API에서는 첫 번째 절만 지원됩니다.

• 제목 설정: 프레임 접근 제한으로 인해 여러 대체 방법을 사용합니다.

• 선택 유지: 일부 작업은 현재 선택 영역에 영향을 줄 수 있습니다.

파일 구조

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

• C 메이저 스케일: 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}

• 2분음표: {"numerator": 1, "denominator": 2}

• 4분음표: {"numerator": 1, "denominator": 4}

• 8분음표: {"numerator": 1, "denominator": 8}

• 점 4분음표: {"numerator": 3, "denominator": 8}