musescore-mcp

MuseScore CLI를 Model Context Protocol(MCP) 서버로 래핑하여 Claude AI에서 악보 파일을 직접 변환·편집·분석할 수 있게 해주는 도구입니다.

---

목적

Claude AI(Claude Desktop, Claude Code 등)에서 MuseScore 악보 파일(.mscz, .musicxml, MIDI 등)을 자연어 명령으로 다룰 수 있도록 합니다.

제공 기능:

카테고리	기능
변환·내보내기	PDF, PNG, MusicXML, MIDI, MP3 등 다양한 포맷 변환; 파트별 악보 추출; 다중 페이지 PNG 내보내기
편집	조성 전조, 음정 전조, 악기별 이조(조옮김); 박자 변경; 빠르기 변경
분석	악보 기본 정보(제목·작곡가·박자·조성·마디 수); 조표 변화 목록; 악기 편성 및 음역 분석; 화성 분석(Roman numeral)
고급	MuseScore 스타일 파일(.mss) 적용; QML 플러그인 실행; MusicXML 문자열로 악보 생성; MIDI → 악보 변환; 폴더 감시 후 자동 변환

---

요구 사항

• Python 3.10 이상
• MuseScore 4 (또는 MuseScore 3) 설치
  • Windows: musescore.org 또는 Microsoft Store
  • 설치 경로가 표준 경로가 아닌 경우 환경 변수 MSCORE_PATH에 실행 파일 경로를 지정

---

설치

1. 저장소 클론

git clone https://github.com/strongbeen04/musescore-mcp.git
cd musescore-mcp

2. 가상 환경 생성 및 패키지 설치

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 기본 설치
pip install -e .

# 화성 분석 기능(music21) 포함 설치
pip install -e ".[harmony]"

3. MCP 서버 등록

Claude Desktop (Windows Store 버전)

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json 파일에 추가:

{
  "mcpServers": {
    "musescore": {
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

Claude Desktop (일반 설치)

%APPDATA%\Claude\claude_desktop_config.json 파일에 추가:

{
  "mcpServers": {
    "musescore": {
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

Claude Code (CLI)

~/.claude.json 파일에 추가:

{
  "mcpServers": {
    "musescore": {
      "type": "stdio",
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

macOS / Linux의 경우 command를 .venv/bin/musescore-mcp로 변경합니다.

설정 저장 후 Claude를 재시작하면 musescore 서버가 연결됩니다.

---

사용법

Claude와 대화하면서 악보 파일을 첨부하거나 경로를 알려주면 됩니다. Claude가 내부적으로 MCP 도구를 호출합니다.

사용 예시:

"이 mscz 파일을 PDF로 변환해줘."
"악보를 Bb 클라리넷 기준으로 이조해줘."
"이 악보의 조성과 마디 수를 알려줘."
"MusicXML을 mscz 파일로 만들어줘."

---

사용 가능한 MCP 도구 목록

도구	설명
get_musescore_path	MuseScore 실행 파일 경로 확인
convert_score	단일 파일 포맷 변환
batch_convert	여러 파일 일괄 변환
export_parts	파트별 악보 개별 추출
export_png_pages	다중 페이지 PNG 내보내기
transpose_by_key	조성 기준 전조
transpose_by_interval	음정 기준 전조
transpose_for_instrument	이조 악기 변환
change_tempo	빠르기(BPM) 변경
change_time_signature	박자표 변경
get_score_info	악보 기본 정보 반환
get_key_signature	조표 변화 목록
list_instruments	악기 편성 및 음역
update_metadata	제목·작곡가 등 메타데이터 수정
analyze_harmony	화성 진행 분석 (music21 필요)
apply_style	MuseScore 스타일(.mss) 적용
run_plugin	QML 플러그인 실행
create_from_musicxml	MusicXML 문자열 → mscz 변환
midi_to_score	MIDI → mscz 변환
watch_folder	폴더 감시 후 자동 변환

---

Purpose

musescore-mcp is an MCP (Model Context Protocol) server that wraps the MuseScore CLI, enabling Claude AI (Claude Desktop, Claude Code, etc.) to convert, edit, and analyze music score files through natural language commands.

Features:

Category	Capabilities
Conversion & Export	Convert to PDF, PNG, MusicXML, MIDI, MP3, and more; extract individual parts; export multi-page PNGs
Editing	Transpose by key or interval; instrument-specific transposition; change tempo and time signature
Analysis	Score metadata (title, composer, key, time signature, measure count); key signature changes; instrument ranges; harmony analysis with Roman numerals
Advanced	Apply MuseScore style files (.mss); run QML plugins; create scores from MusicXML strings; convert MIDI to score; auto-convert files in a watched folder

---

Requirements

• Python 3.10 or higher
• MuseScore 4 (or MuseScore 3) installed
  • Windows: musescore.org or Microsoft Store
  • If installed to a non-standard path, set the MSCORE_PATH environment variable to the executable path

---

Installation

1. Clone the repository

git clone https://github.com/strongbeen04/musescore-mcp.git
cd musescore-mcp

2. Create a virtual environment and install

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Base install
pip install -e .

# With harmony analysis support (music21)
pip install -e ".[harmony]"

3. Register the MCP server

Claude Desktop (Windows Store)

Edit %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "musescore": {
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

Claude Desktop (Standard install)

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "musescore": {
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

Claude Code (CLI)

Edit ~/.claude.json:

{
  "mcpServers": {
    "musescore": {
      "type": "stdio",
      "command": "C:\\path\\to\\musescore-mcp\\.venv\\Scripts\\musescore-mcp.exe"
    }
  }
}

On macOS / Linux, change command to .venv/bin/musescore-mcp.

Restart Claude after saving the config to connect the server.

---

Usage

Attach a score file in your Claude conversation or describe its path, and ask in natural language. Claude will call the appropriate MCP tools automatically.

Examples:

"Convert this mscz file to PDF."
"Transpose this score for Bb clarinet."
"What is the key and measure count of this score?"
"Create an mscz from this MusicXML."

---

Available MCP Tools

Tool	Description
get_musescore_path	Return the detected MuseScore executable path
convert_score	Convert a single score to another format
batch_convert	Convert multiple files in one call
export_parts	Export each instrument part as a separate file
export_png_pages	Export all pages as individual PNG images
transpose_by_key	Transpose to a target key
transpose_by_interval	Transpose by a specific interval
transpose_for_instrument	Rewrite transposition for a given instrument
change_tempo	Set a new tempo (BPM)
change_time_signature	Change the time signature
get_score_info	Return title, composer, key, time sig, tempo, parts, measure count
get_key_signature	List all key signature changes with measure numbers
list_instruments	Return instrument names, transpositions, and pitch ranges
update_metadata	Edit title, composer, lyricist, and copyright fields
analyze_harmony	Analyze chord progressions (requires music21)
apply_style	Apply a MuseScore style file (.mss)
run_plugin	Execute an installed MuseScore QML plugin
create_from_musicxml	Create an mscz from a MusicXML string
midi_to_score	Convert a MIDI file to mscz
watch_folder	Monitor a folder and auto-convert new .mscz files

---

License

MIT