musescore-mcp

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

목적

Claude AI(Claude Desktop, Claude Code 등)에서 MuseScore 악보 파일(.mscz, .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 도구 목록

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:

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

License

MIT