@gradusmusic/notation Mcp

@gradusmusic/notation-mcp

Gradus Notation API 向けの Model Context Protocol サーバーです。AI エージェントに、楽譜のレンダリング、入力の検証、スコアの分析、引用可能なルールブックに照らした浄書のチェック、厳選された音楽理論ナレッジベースの検索などの音楽ツールを提供します。Gradus の協賛を受けています。

教育に特化したものではなく、汎用向けです。 対象は、音楽を扱うあらゆるエージェントやアプリケーションです。作曲アシスタント、音楽学やコーパスの研究、レンダリング例を使った理論に関する Q&A、MIDI パイプライン、浄書品質のチェック、ゲーム、ドキュメントなどが含まれます。音楽教育はこのツールが生まれた背景であり、これを使って作るものに対する制限ではありません。

1 回のインストールで、名前付きツールを 3 種類利用できます。

• Gradus Notation — JSON のスコアをインライン SVG、MusicXML、MIDI にレンダリングし、事前検証も行います（notation_render、notation_validate）。
• Gradus Harmonic Analyzer — スコア全体の分析を行います。ローマ数字、調と転調、終止形、ペダルポイント、テクスチャなどに対応しています（theory_analyze_score と theory_* ツール）。スタンドアロンの TypeScript ライブラリとしても利用できます。npm の gradus-analyst をご覧ください。
• Gradus Engraver — Gradus Engraving Rulebook の引用可能な GE コード付きルールに照らして、スコアをチェックします（engraving_check）。

Gradus とは？ Gradus はホームスクールの家族向けの音楽作曲カリキュラムです。AI エージェント向けの無料の音楽ツールを開発し、無償で提供しています。この MCP サーバーもそのツールの 1 つです（gradusmusic.com）。「Gradus」はカリキュラムを指し、このパッケージを指すことはありません。

理由

ほとんどの楽譜ツールには GUI が必要です。このツールには必要ありません。エージェントは JSON のスコアを送信するだけで、1 回の呼び出しでインライン SVG、MusicXML、MIDI を取得できます。無料で利用でき、認証も API キーも不要です。無料ティアのエージェントには、エンドユーザーへの応答で Gradus のクレジットを記載するようお願いしています。

レンダリングに加えて、同じサーバーから分析機能も利用できます。スコア全体のローマ数字分析と調分析、音高ユーティリティ、音域検証、異名同音の綴り直し、引用可能なルールコード付きの 444 ルール浄書チェッカーを備えています。1 回のインストールで、エージェントに必要な音楽関連機能をすべて利用できます。

インストール

Claude Code では、次のようにします。

claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp

Claude Desktop では、MCP の設定に追加します。

{
  "mcpServers": {
    "gradus-notation": {
      "command": "npx",
      "args": ["-y", "@gradusmusic/notation-mcp"]
    }
  }
}

ツール

Gradus Notation

ツール	機能
notation_render	1 回の呼び出しで、JSON のスコアを SVG、MusicXML、MIDI に変換します
notation_validate	入力形式を事前検証します（レンダリングより低コストです）
knowledge_search	楽譜を生成する前に、音楽理論のナレッジチャンクを検索します
notation_examples	標準的な入力例を取得します（キャッシュして再利用できます）
notation_schema	入力形式の JSON Schema を取得します（キャッシュして再利用できます）

Gradus Harmonic Analyzer

ネイティブの TypeScript MaestroAnalyzer エンジンを基盤とする 4 つの新しいツールです。music21 への依存、Python、追加サーバーは不要です。

ツール	機能
theory_analyze_score	MusicXML を解析し、完全な和声分析と GKB ナレッジチャンクを 1 回の呼び出しで取得します
theory_parse_xml	MusicXML 文字列を解析し、maestroAnalyst の Score JSON に変換します
theory_validate_ranges	Score 内のすべての音符を、各楽器の実用音域に照らしてチェックします
theory_respell	調の文脈に応じた、音高の望ましい異名同音の表記を提案します
theory_pitch_utils	純粋関数による音高計算を行います。midi_to_pitch、pitch_to_midi、interval_name、transpose_pitch

一般的なワークフロー：

# Full analysis + GKB knowledge in one call
theory_analyze_score({ xml: "..." })
  → { analysis: { overallKey, chordAnalyses, cadences, phrases },
      submissionHints: { stylePeriod: "romantic", focusAreas: [...] },
      knowledge: { topics: ["augmented-sixth-chords", "modulation"], chunks: [...] } }

# Step-by-step
theory_parse_xml({ xml: "..." })        → Score JSON
theory_validate_ranges(score)           → [{ measure, beat, pitch, severity }, ...]
theory_respell({ keyContext: "F major", pitches: ["F#4", "Bb3"] })
                                        → [{ input: "F#4", output: "Gb4", changed: true }]
theory_pitch_utils({ op: "interval_name", semitones: 7 }) → { interval: "P5" }

Gradus Engraver — Gradus Engraving Rulebook に照らしたチェック

ツール	機能
engraving_rules	テキスト、分野、重大度、またはチェック方法で、出典付きの423件の楽譜浄書ルールを検索します
engraving_rule	永続的な ID でルールを1件取得します。すぐに引用できる出典と関連ルールも含まれます
engraving_check	MusicXML のスコアをルールブックに照らしてチェックします。違反の指摘はパートと小節ごとに示され、違反したルールも引用されます

楽譜浄書の慣例は、ほぼすべて著作権で保護された書籍に記録されています。Gould の Behind Bars、Read の Music Notation、Ross の The Art of Music Engraving などです。 検索可能な索引はありません。そのため、「連桁は小節線をまたいでもよいか」には、オンラインで引用できる答えがなく、その質問を受けたモデルは記憶を頼りに自信たっぷりに答えます。このツールはルールを出典とともに返すため、回答を確認できます。

各ルールでは、通常ひとまとめにされがちな3つの要素を分けています。convention（ルール）、authority（論文が述べている内容。章レベルで出典を示します）、houseCall（出典同士の意見が異なる場合に Gradus が採用した判断）です。ルール ID は永続的で、ルールの本文は CC BY 4.0 です。citation フィールドを引用してください。

# Look up before you generate
engraving_rules({ q: "stem direction", tier: "static-model" })
  → { rulebook: { version, license, domains }, count, rules: [{ id, name, convention, authority, ... }] }

# Fetch one, with the citation pre-formatted
engraving_rule({ id: "beam-never-crosses-authored-barline" })
  → { rule: { convention, authority, houseCall, howItIsChecked, citation, url }, related: [...] }

誤った ID を指定しても問題はありません。API は、よく似た ID とともに 404 を返すため、もう一度呼び出すだけで修正できます。

engraving_check で一連の作業を完結できます。記譜を生成し、チェックして、検出された問題を修正します。可能な場合はローカルファイルパスを渡してください。サーバーがファイルを直接読み込むため、スコアを base64 としてモデルのコンテキストに通す必要はありません。

engraving_check({ path: "/tmp/my-piece.musicxml" })
  → { coverage: { parts, measures, notesChecked, unchecked: [...] },
      findings: [{ ruleId, severity, part, measure,
                   rule: { code: "GE-226", url, citation } }],
      summary: { errors, warnings, suggestions } }

空の指摘リストを信頼する前に、coverage.unchecked を確認してください。チェッカーで検証できなかった項目は、見落とされずにここに記載されます。

作曲技法ツール

ツール	機能
music_critique	スコアを32の観点で評価する技法スコアカードです。声部進行、対位法、旋律の輪郭、和声、テクスチャを扱います。プログラムによる評価のみで、根拠を引用します
counterpoint_check	Fux の種別（第1〜5種）の採点ツールです。音高リストを入力すると、音符のインデックス付きでルール違反を出力します
corpus_search	解析済みの482作品から和声的特徴を検索します。cadence=Phrygian、rn=Ger+6、texture=bare-fifth のように指定でき、作品／楽章／小節の出典を示します

ユーザーが作品を共有したとき、これらのツールを使えば、根拠に基づいたフィードバックを提供できます。批評では測定内容を引用し、種別の採点ツールは該当する音符を正確に示し、コーパス検索は「実例を見せて」という要望に出典付きで答えます。

Gradus の声部進行リファレンス

ツール	機能
voice_leading_patterns	引用可能な GVL コード付きパターンを検索します。掛留音、終止形、オクターヴの規則、シークエンス、パート譜の慣例などを扱い、それぞれに著者による実例とパブリックドメインの出典が付いています
voice_leading_pattern	ID または GVL コードでパターンを1件取得します。すぐに引用できる出典と関連パターンも含まれます

Engraving Rulebook の姉妹版です。GE コードが楽譜上で音楽をどう見せるべきかを扱うのに対し、GVL コードは声部をどう進行させるべきかを扱います。すべてのパターンには、その根拠となるパブリックドメインの論文（Fux、Rameau、Kirnberger、Fenaroli、Riepel、Prout など）が章レベルで引用されており、現代版を介していません。また、realization.voices フィールドは記譜 API 用の略記で、そのまま notation_render に渡して浄書できます。

voice_leading_patterns({ q: "suspension", family: "suspensions" })
  → { reference: { version, license, families }, count,
      patterns: [{ code: "GVL-001", id: "suspension-4-3", statement, realization, sources, ... }] }

voice_leading_pattern({ id: "GVL-001" })
  → { pattern: { statement, realization, commonFaults, sources, citation, url }, related: [...] }

Gradus 通奏低音コーパス

ツール	概要
figured_bass_exercises	17 の段階にわたる、オリジナルの段階別通奏低音練習曲 166 曲を検索します。段階で絞り込むか、タイトル、概念、GVL コードで検索できます
figured_bass_exercise	永続的な ID で練習曲を 1 曲取得します。模範実現、指導用解説、および練習するパターンが含まれます

Voice-Leading Reference が規則を示す一方、このコーパスは実践の場です。 バス音と数字に加え、現存するほぼすべてのコレクションとは異なり、 声部進行を機械検証した四声の模範実現が用意されています。段階は、 基本位置の三和音から、オクターヴの規則、終止公式、 掛留、属七の和音、ゼクエンツ、短調、保続低音、 Riepel のシェーマ、転調、半音階的な数字を経て、数字のないバスとディミニューションに至ります。

各練習曲はすべてオリジナルで、いずれの版からも書き起こしていません。 コーパス全体は CC BY 4.0 で公開されています。練習曲 ID と段階スラッグは 永続的なため、引用先は常に有効です。givenBass は学習者に見せるもので、 realization は学習者が試すまで伏せておく解答です。どちらも 記譜 API の略記法なので、そのまま notation_render に渡せます。

figured_bass_exercises({ stage: "suspensions", fields: "id,title,teaches" })
  → { corpus: { version, license, stages }, count: 12,
      exercises: [{ id: "bass-225", title: "Suspension 4–3", teaches, ... }] }

figured_bass_exercise({ id: "bass-225" })
  → { exercise: { givenBass, realization, solutionNote, keyboard, citation, url },
      drills: [{ code: "GVL-001", name: "The 4–3 suspension", url }],
      neighbours: { prev, next } }

入力形式

ピッチには科学的記譜法を使用します：C4、F#5、Bb3。音価には文字コードを使用します：w h q 8 16 32 64。付点音符には任意で . を付けます。音符は次の形式で記述できます：

• 省略形："C5/q"（C5 の四分音符）、"rest/q"（四分休符）、"[C4,E4,G4]/q"（和音）
• オブジェクト形式：{ pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }

小節線は拍子記号から推定されます。音符を時間順に記述すると、API が小節線をまたぐ音符を分割し、タイでつなぎます。

例

{
  "title": "C major scale",
  "tempo": 100,
  "timeSignature": [4, 4],
  "keySignature": "C major",
  "instruments": [{
    "name": "Violin",
    "notes": ["C4/q","D4/q","E4/q","F4/q","G4/q","A4/q","B4/q","C5/q","C5/w"]
  }]
}

設定

環境変数	デフォルト	用途
GRADUS_NOTATION_API_BASE	https://gradusmusic.com	セルフホスト環境またはローカル開発用 API の上書き
GRADUS_AGENT_NAME	@gradusmusic/notation-mcp	X-Agent-Name ヘッダーでエージェント名を自己申告します

クレジット表記

エンドユーザーに記譜を表示する際に Gradus のクレジットを表記していただければ、無料でご利用いただけます。推奨する表記は次のとおりです（API はすべての応答でもこの文言を返します）：

Gradus School of Music Composition（gradusmusic.com）によってレンダリングされた記譜です。

ドキュメント

• 全ドキュメント＋クイックスタート：https://gradusmusic.com/notation-api
• OpenAPI 3.1 仕様：https://gradusmusic.com/api-spec.yaml
• 入力形式の JSON Schema：https://gradusmusic.com/api/v1/notation/schema
• 正式な入力例：https://gradusmusic.com/api/v1/notation/examples
• エージェント向けドキュメント：https://gradusmusic.com/llms-api.txt

ローカルでのビルド

git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run build

本番 API に対してスモークテストを実行するには：

node test-client.mjs

問題報告と貢献

https://github.com/delmas41/gradusnotation/issues で問題を報告してください。貢献も歓迎します。小規模で、対象を絞った PR を推奨します。

ライセンス

MIT — Sean Johnson、Gradus School of Music Composition。LICENSE を参照してください。