Drives the official MuseScore Studio 4.7.6 headless to inspect and fix score layout: system and page breaks, systems of N measures, measure stretch, style values, element offsets, fitting a score to N pages, overlap detection via rendered SVG, undoable versioned edits, and PNG/PDF export, without modifying the original score file.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@musescore open my quartet score and fit it onto 3 pages"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server (stdio, TypeScript) that drives the official MuseScore Studio 4.7.6 headless to inspect and fix score layout: system and page breaks, systems of N measures, measure stretch, style values, element offsets, fitting a score to N pages, overlap detection (including notes and staff lines, via the rendered SVG), and PNG / PDF export. The original score file is never modified: the server works on a copy, and every change creates a new version that you can undo.
Requirements: macOS, Node.js 22+, MuseScore Studio 4.7.6 at /Applications/MuseScore 4.app
Setup: git clone, npm ci, then register it with Claude Code (see "起動と Claude Code への登録" below)
License: MIT. MuseScore itself is a separate application (GPL-3.0) and is not included in this repository.
The rest of this README is written in Japanese.
Related MCP server: word-mcp
公式版 MuseScore Studio 4.7.6 を画面なしで呼び、譜面のレイアウト（改段・改ページ・小節の伸び縮み・スタイル・記号の位置）を 調べて直す MCP サーバー（stdio・TypeScript）。
設計と経緯: docs/prototype-notes.md（試作の作業メモ）
やること | MuseScore のどの経路を使うか |
改段・改ページ・セクション区切り・nobreak・小節の伸び縮み・記号の位置ずらし・autoplace | 拡張機能 |
スタイル | 変えるキーだけ書いた |
N 小節ごとに改段 | 拡張機能で |
N ページに収める | 詰める値の |
描画・情報 |
|
元の譜面ファイルには書き込まない。開いたときに作業フォルダへコピーし、mscore -o で 4.x 形式に正規化した版 v000 から始める。
変更のたびに新しい版（v001, v002…）を作る。score_undo は版を戻すだけ。
版のファイル名は使い回さない（戻した後に変更すると、版の番号は同じでもファイルは新しい番号になり、捨てた版のファイルも残る）。
描画・SVG・レイアウトのキャッシュは版のファイル名で引くので、捨てた版の画像や重なりが返ることはない。
同じ譜面（score_id）への呼び出しは、1 つずつ順に行う（前の呼び出しが終わってから、今の版と新しい版のファイル名を決める）。
Claude Code が同じ譜面へ道具を並列に呼んでも、どの変更も消えない。別の譜面への呼び出しは待ち合わない。
保存は score_save だけ。既存のファイルは overwrite=true のときだけ上書きし、先に <名前>.bak-日時ミリ秒-乱数 の控えを作る
（控えは既存のファイルを上書きしない作り方なので、続けて上書きしても控えは毎回別に残る）。
中身は同じフォルダの一時ファイルに作ってから、新規なら link（既にあれば失敗）、上書きなら rename で置き換える。
次の場所には保存しない。
書き込み禁止のフォルダ（MSCORE_MCP_READONLY_DIRS、既定は試験譜面の testscores）と、作業フォルダ全体（MSCORE_MCP_WORK。ほかの譜面の版も含む）。
保存先の親フォルダを realpath してから比べ、大文字小文字の違いも同じフォルダとみなす（祖先フォルダの dev/ino でも照合する）ので、
記号リンクのフォルダ経由や TESTSCORES のような書き方でも拒む。
保存先そのものが記号リンクのとき（リンク先を書き換えない）。
画面ありの MuseScore は起動しない。
名前 | 何をするか |
| 譜面（.mscz/.mscx/.musicxml/.mxl）を開き、概要と段の並びを返す |
| 版の一覧／版を戻す |
| ページを PNG で返す |
| 段・ページ・小節・記号の位置と重なりの候補（ |
| 改段・改ページ・セクション区切り・nobreak を入れる/外す |
| 小節の伸び縮み |
| N 小節ごとに改段（ |
| N ページに収める（間隔を詰め、spatium を二分探索して焼き込む） |
| スタイルのキー一覧／読む／変える |
| 記号をずらす（autoplace も切り替えられる） |
| 2 つの版を比べる（段・小節・スタイル・画素） |
| 保存（.mscz / .pdf） |
経路 | 見えるもの | id |
拡張機能の bbox（ | 記号どうし（強弱・歌詞・テキスト・ヘアピンなど） | あり |
SVG の bbox（ | 音符・符幹・譜線を含む、描かれたもの全部 | 記号の側に照合して付ける |
SVG の塊（class=型名、単位 1/1200 inch、ページの左上が原点）と記号（型、ページ座標の sp）を、
ページ・型・座標で照合する。換算は 1 sp = spatium[mm] × 1200 / 25.4。
塊の面積の 50% 以上が記号の bbox に入るものを候補にし、重なりの大きい順に 1 対 1 で割り当てる。
重なりごとに movable（動かせる側の id・suggestedDy・direction・alternatives）を返す。
suggestedDy は、上下それぞれ相手から 0.3 sp 離し、そこで譜線・符幹・ほかの記号に当たればそれも越える位置まで進め、動きの小さい方。
そのまま element_offset（id, dy）に渡せる。autoplace=true の記号は MuseScore が押し戻すことがあるので、rectAfter で確かめる。
制限: 小さい譜表（mag≠1）の記号は座標の単位がずれるので、照合できないことがある（unmatched に数が出る）。
前提: macOS、Node 22 以上、公式版 MuseScore Studio 4.7.6（/Applications/MuseScore 4.app）。
段の固定（layout_systems_every の method=lock）は MuseScore 4.6 以降の機能。スタイルの一覧は 4.7.6 に合わせている。
git clone https://github.com/bgng-co-jp/musescore-mcp.git ~/projects/musescore-mcp-server
cd ~/projects/musescore-mcp-server
npm ci
npm run typecheck
npm test # MuseScore を使わない単体の試験npx tsx src/server.ts # stdio で待つ（手で試すとき）Claude Code への登録（ユーザー範囲）。環境変数は -e で渡す。
claude mcp add --scope user musescore \
-e MSCORE_SANDBOX=$HOME/projects/musescore-mcp/sandbox-config/server \
-- $HOME/projects/musescore-mcp-server/node_modules/.bin/tsx $HOME/projects/musescore-mcp-server/src/server.tsMSCORE_SANDBOX は普段の MuseScore の設定と分けるためのフォルダ（下の「環境変数」）。省略すると <リポ>/.sandbox を使う。
すべて任意。未設定なら既定値を使う。一覧は .env.example にもある。秘密の値は使わない。
サーバーは .env を読み込まない。Claude Code に登録するときは claude mcp add -e 変数=値 で、手で起動するときはシェルの環境変数で渡す。
変数 | 既定値 | 内容 |
|
| mscore 本体 |
|
| mscore の設定フォルダの親。4.7.6 には |
|
| 譜面の作業コピー（版）と mscore の起動記録（ |
|
| 保存を拒むフォルダ（ |
|
| タイムアウトの既定値（情報 120 秒・書き出し 180 秒・描画 300 秒・拡張機能 180 秒）に掛ける係数。大きい譜面なら |
|
| 1 つのサーバーの中で同時に動かす mscore の数 |
|
| 失敗した回の |
mscore は呼び出しごとに <MSCORE_SANDBOX>/runs/<runId>/ を HOME にして起動する（runId = 時刻・サーバーの pid・乱数）。
拡張機能 mcpb1 と引数 params.js はその中の Library/Application Support/MuseScore/MuseScore4/extensions/mcpb1/ に置く。
試作は設定フォルダの params.js を共有していたので、サーバーを 2 つ動かすと引数が混ざるおそれがあった。
ログもその中にできる。失敗したときはその回のログの ERROR 行を応答に入れ、ログの場所も返す （共有の HOME だとログ名が起動秒単位なので、同じ秒に起動した別の回と同じファイルに混ざる）。
新しい HOME での起動に余分な時間はかからない（実測 0.67 秒 / 使い回し 0.65 秒、Amazing_grace の PDF 書き出し）。
どの呼び出しにもタイムアウトが必須。超えたらプロセスグループごと SIGTERM → 3 秒後に SIGKILL。
サーバーが終わるときも、自分が起動して動いている mscore だけを止める。起動と終了は mscore-pids.log に残る。
制限: mscore は別のプロセスグループで起動するので、サーバーの node が SIGKILL などで強制終了されると、その時に動いていた mscore は
タイムアウトまで残ることがある（クライアントが正常に閉じた場合は止まる）。そのときは mscore-pids.log で end の無い pid を探して止める。
種類 | コマンド | MuseScore | 場所 |
型検査 |
| 使わない | CI と手元 |
単体 |
| 使わない | CI と手元 |
端から端まで |
| 使う（画面なし） | macOS の手元だけ |
追加 |
| 使う（画面なし） | macOS の手元だけ |
e2e は MCP の client SDK でこのサーバーを stdio で起動し、道具を順に呼んで確かめる。出力は e2e-out/。
試験譜面は MSCORE_MCP_TESTSCORES（既定 ~/projects/musescore-mcp/testscores）から読むだけで、書き込まない。
試験譜面はこのリポジトリに含めていない（MuseScore の楽譜を各自で用意する）。
MSCORE_SANDBOX=$HOME/projects/musescore-mcp/sandbox-config/A-fix npm run e2e
E2E_SECTIONS=fixes MSCORE_SANDBOX=... npm run e2e # 節を選ぶとき（b1,harden,tools,overlap,fixes）GitHub では .github/workflows/ci.yml が型検査と単体の試験を走らせる。.gitlab-ci.yml は社内の GitLab 用（社内の共通テンプレートを使うので、社外からは使えない）。
Linux の runner に MuseScore が無いので、CI で走るのは型検査・単体の試験（社内の GitLab では秘密スキャンも）だけ。
常駐サービスではない（Claude Code が必要なときに stdio で起動する）。配備は「clone → npm ci → claude mcp add」だけ。
MIT。MuseScore Studio は別のアプリケーション（GPL-3.0）で、このリポジトリには含まない。
このサーバーは MuseScore を外部のプログラムとして呼び出す。data/style-catalog.json は MuseScore 4.7.6 のスタイルのキー名・型・既定値の一覧に、説明を付けたもの。
記号（強弱・歌詞・テキスト・テンポ・ヘアピンの区間など）の位置をずらす。対象は layout_inspect の要素 id（例 DYNAMIC#3、HAIRPIN#0.1）か、type＋measure（＋staff, nth）で指す。mode=relative（既定）は今の位置から dx,dy（sp、y は下向きが正）だけ動かす。absolute は offset そのものを x,y にする。autoplace=false にすると MuseScore が自動で押し戻さなくなる（重なっても動かさない）。
Inputs: score_id (required), dx, dy, id, +6 more.
譜面を pages ページ以内に収める。tighten=true（既定）なら、まず縦方向の自動の広げ（enableVerticalSpread）を切り、段・譜表の間隔（minSystemDistance 4 / maxSystemDistance 8 / staffDistance 5 / akkoladeDistance 5 sp、今の値がこれより小さければそのまま）を詰める。そのうえで MuseScore 自身のレイアウトで spatium（譜表の大きさ, mm）を二分探索し、収まる一番大きい値を mscore -S で焼き込んで新しい版を作る。すでに収まっていれば何もしない（max_spatium_mm を指定すると、その大きさまで広げてよい）。
Inputs: pages (required), score_id (required), tighten, max_spatium_mm, +1 more.
段・ページごとの小節の並び、各小節の幅・伸び縮み・改段、記号（強弱・歌詞・テキスト・ヘアピン等）の位置と、重なりの候補を返す。座標は sp（譜表の1間）単位。要素の id（例 DYNAMIC#3, LYRICS#10, HAIRPIN#0.1）は element_offset に渡せる。小節は 1 始まりの通し番号（譜面の先頭からの並び順。弱起や番号を飛ばした小節があると表示上の小節番号とずれることがある。layout_inspect の measures[].index / no で対応を確認できる）
Inputs: score_id (required), measure_to, measure_from, svg_overlaps, +3 more.
指定した小節の終わりに区切りを入れる。kind: line=改段, page=改ページ, section=セクション区切り, nobreak=この小節の後で段を切らない, none=区切りを外す。その小節に既にある区切りは置き換える。MuseScore の API（画面なし）で行い、新しい版を作る。小節は 1 始まりの通し番号（譜面の先頭からの並び順。弱起や番号を飛ばした小節があると表示上の小節番号とずれることがある。layout_inspect の measures[].index / no で対応を確認できる）
Inputs: kind (required), measures (required), score_id (required).
小節の範囲に伸び縮み（userStretch。1=標準、1より大きいと広く、小さいと狭く）を設定する。MuseScore の描画では 0.1〜10 に収められる。小節は 1 始まりの通し番号（譜面の先頭からの並び順。弱起や番号を飛ばした小節があると表示上の小節番号とずれることがある。layout_inspect の measures[].index / no で対応を確認できる）
Inputs: from (required), value (required), score_id (required), to.
小節の範囲（既定は全体）を every 小節ずつの段にする。method=lock（既定）は MuseScore 4.6 以降の段の固定（メニューの「改段の追加/削除」と同じ。幅が足りなくても N 小節に収める）、method=breaks は N 小節ごとに改段を入れる（幅が足りないと MuseScore がそれより手前で段を切る）。範囲の中の改段・nobreak は先に外す（改ページ・セクション区切りは残して keptBreaks で返す）。小節は 1 始まりの通し番号（譜面の先頭からの並び順。弱起や番号を飛ばした小節があると表示上の小節番号とずれることがある。layout_inspect の measures[].index / no で対応を確認できる）
Inputs: every (required), score_id (required), to, from, +1 more.
2 つの版（既定は 1 つ前と今）を比べ、ページ数・段数・段ごとの小節数、小節ごとの伸び縮み/改段の差、スタイルの差、ページ画像の画素の差を返す。
Inputs: score_id (required), to, dpi, from.
譜面ファイル（.mscz/.mscx/.musicxml/.mxl）を作業用にコピーして開き、概要（題名・パート・小節数・ページ数・段の並び）を返す。元のファイルには書き込まない。以後の操作は返った score_id で行う。
Inputs: path (required).
今の版（または指定した版）のページを PNG に描いて画像で返す。dpi は 30〜200（既定 80）。一度に返すのは 4 ページまで。
Inputs: score_id (required), dpi, pages, version.
今の版を保存する（.mscz、または .pdf で書き出し）。既定では既存のファイルを上書きしない。overwrite=true のときだけ上書きし、その前に「<名前>.bak-日時ミリ秒-乱数」の控えを作る（控えは上書きしない）。書き込み禁止のフォルダ（既定は試験譜面のフォルダ）と作業フォルダには保存できない（記号リンクのフォルダ経由・大文字小文字の違いでも拒否）。保存先そのものが記号リンクのときも拒否する。
Inputs: path (required), score_id (required), overwrite.
開いている譜面の版（番号 0=開いた直後、以降は変更ごと）と、今の版を返す。版のファイル名は使い回さないので、戻した後に変更すると番号とファイル名の数字がずれる。
Inputs: score_id (required).
今の版を steps だけ前に戻す（ファイルは消さない。戻した後に変更すると、その先の版は捨てる）。
Inputs: score_id (required), steps.
今の版のスタイル値（score_style.mss）を読む。譜面に書かれていないキーは既定値を返す。
Inputs: keys (required), score_id (required).
レイアウトに効くスタイルのキー（v4.7.6 の Sid）を、型・単位・既定値・説明付きで返す。既定はよく使う 60 件余り。query で名前や説明を検索すると全 1972 件から探す。
Inputs: query, category.
スタイルのキーと値をまとめて設定する（例 {"spatium":1.5, "minSystemDistance":10}）。単位: SPATIUM 型は sp、page* はインチ、spatium は mm、BOOL は true/false、POINT は {x,y}。値は型で検査する。変えるキーだけの .mss を作り mscore -S で焼き込んで新しい版を作り、変更前後のページ・段を返す。注意: enableVerticalSpread=true の間は staffDistance/akkoladeDistance/minSystemDistance が効かない。pageWidth を変えるときは pagePrintableWidth も変える。
Inputs: values (required), score_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
Most tools target a clearly distinct object+action pair (style_get reads values vs. style_list enumerates keys; score_status reports the current version vs. score_compare diffs two versions). The main overlap is between layout_set_break, layout_systems_every, and layout_fit_pages, which all manipulate breaks/spacing, but the descriptions explicitly differentiate them (systems_every clears existing breaks, fit_pages tunes spatium and distances). An agent could still occasionally hesitate between set_stretch and element_offset for spacing tweaks, but overall boundaries hold.
Strong, predictable prefix-namespace pattern (score_*, style_*, layout_*, element_*) in consistent snake_case, with verb-ish suffixes (open, save, undo, render, compare, set, offset). Minor deviations: score_status and element_offset are noun_noun with no verb, and layout_systems_every / layout_fit_pages use unusual non-verb phrasing. Still readable and groupable at a glance.
15 tools sits at the top of the ideal range but each maps to a concrete operation in the edit-render-save workflow (open/status/undo/compare/save plus style and layout subtools). Nothing appears redundant enough to drop, and the surface is not so large that selection becomes a burden.
Lifecycle coverage is solid: open, status, undo, compare, render, and save/export (mscz/pdf) plus full style read/list/set and layout inspection/break/stretch/system/fit/element-offset operations. Gaps are minor: no redo, no explicit close/reset of a score, no direct note or metadata editing, and no way to apply a style preset wholesale — all workable around given the layout-focused scope.
Convert MusicXML, MIDI, ABC, MEI and Humdrum, print sheet music, and verify every note survived.
Audit and repair any public GitHub repo. Free survey; paid source, unified diffs and a pull request.
Read-only sheet music discovery and practice tools, with browser-local recognition guidance.
Free CSV and SRT diagnostics with deterministic $3 one-file repairs.