This server provides an MCP interface to the Gradus Notation API, enabling AI agents to render, validate, and analyze music notation, search a music theory knowledge base, and manipulate pitches — all without a GUI.
notation_render: Convert a JSON score into inline SVG, MusicXML, and MIDI in a single call. Supports scientific pitch notation, duration codes, chords, rests, dynamics, articulations, and multi-voice instruments. Bar lines are automatically inferred and notes crossing bar lines are split and tied.
notation_validate: Pre-flight check a JSON score for errors with concrete fix suggestions — cheaper than a full render, ideal for iterating on input shape.
knowledge_search: Search a curated music theory knowledge base including hand-authored curriculum content, analysis of 408 Bach chorales, score commentaries on 50+ orchestral works, and historical sources from Fux through Boulanger. Useful for voice leading rules, cadence realizations, and style-specific theory facts.
notation_examples: Fetch canonical input examples (single melody, counterpoint, chord progressions, tied notes, string quartet snippets) to use as references or starting points.
notation_schema: Retrieve the full JSON Schema for the notation_render input format.
theory_analyze_score: Perform full harmonic analysis of a MusicXML score, including key detection, chord analyses, cadences, and phrases.
theory_parse_xml: Convert a MusicXML string into a structured Score JSON object.
theory_validate_ranges: Check every note against the practical ranges of their assigned instruments.
theory_respell: Suggest preferred enharmonic spellings for pitches in a given key context.
theory_pitch_utils: Pure functions for MIDI/pitch conversion, interval naming, and transposition.
Model Context Protocol server for the Gradus Notation API. Gives AI agents music tools: render notation, validate input, analyze scores, check engraving against a cited rulebook, and search a curated music-theory knowledge base — sponsored by Gradus.
General-purpose, not education-specific. Any agent or application that works with music is the audience — composition assistants, musicology and corpus research, theory Q&A that wants rendered examples, MIDI pipelines, engraving quality checks, games, documentation. Music education is where the tool comes from, not a restriction on what you build with it.
One install, three named tools:
Gradus Notation — render a JSON score to inline SVG, MusicXML, and MIDI, with pre-flight validation (notation_render, notation_validate).
Gradus Harmonic Analyzer — full-score analysis: Roman numerals, keys and modulations, cadences, pedal points, texture (theory_analyze_score and the theory_* tools). Also a standalone TypeScript library: gradus-analyst on npm.
Gradus Engraver — checks a score against the Gradus Engraving Rulebook's citable GE-coded rules (engraving_check).
What is Gradus? Gradus is a music-composition curriculum for homeschool families; it builds and gives away free music tools for AI agents. This MCP server is one of those tools (gradusmusic.com) — "Gradus" refers to the curriculum, never to this package.
Most music-notation tools require a GUI. This one doesn't. An agent can submit a JSON score and get back inline SVG, MusicXML, and MIDI in a single call. Free to use, no auth, no API key — agents on the free tier are asked to credit Gradus in their response to the end user.
Beyond rendering, the same server exposes the analysis side: Roman-numeral and key analysis of a full score, pitch utilities, range validation, enharmonic respelling, and a 444-rule engraving checker with citable rule codes. One install covers the whole music surface an agent needs.
Related MCP server: Fast Mermaid Validator MCP
In Claude Code:
claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcpIn Claude Desktop, add to your MCP config:
{
"mcpServers": {
"gradus-notation": {
"command": "npx",
"args": ["-y", "@gradusmusic/notation-mcp"]
}
}
}Tool | What it does |
| JSON score → SVG + MusicXML + MIDI in one call |
| Pre-flight validate input shape (cheaper than render) |
| Look up music-theory chunks before generating notation |
| Canonical input examples (cache and reuse) |
| JSON Schema for the input shape (cache and reuse) |
Four new tools backed by the native TypeScript MaestroAnalyzer engine — no music21 dependency, no Python, no extra server.
Tool | What it does |
| Parse MusicXML → full harmonic analysis + GKB knowledge chunks in one call |
| Parse a MusicXML string → maestroAnalyst |
| Check every note in a Score against its instrument's practical range |
| Suggest preferred enharmonic spelling for pitches in a key context |
| Pure-function pitch arithmetic: |
Typical workflows:
# 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" }Tool | What it does |
| Search 423 sourced music-engraving rules by text, domain, severity, or how they are checked |
| Fetch one rule by its permanent id, with a ready-to-quote citation and related rules |
| Check a MusicXML score against the rulebook — findings by part and measure, each citing the rule it breaks |
Engraving practice is documented almost entirely in copyrighted print — Gould's Behind Bars, Read's Music Notation, Ross's The Art of Music Engraving — with no searchable index. So "may a beam cross a barline" has no citable answer online, and a model asked that question answers confidently from memory. These tools return the rule with its source, so the answer can be checked.
Each rule separates three things that are usually mashed together: convention
(the rule), authority (what the treatises say, cited at chapter level), and
houseCall (where Gradus came down when the sources disagree). Rule ids are
permanent and rule text is CC BY 4.0 — quote the citation field.
# 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: [...] }A wrong id is cheap: the API answers 404 with near-matching ids, so you can correct in one more call.
engraving_check closes the loop: generate notation, check it, fix what it
finds. Pass a local file path when you can — the server reads it directly, so
the score never has to travel through the model's context as 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 } }Read coverage.unchecked before trusting an empty findings list — anything the
checker could not verify is named there rather than silently passed.
Tool | What it does |
| 32-dimension craft scorecard for a score — voice leading, counterpoint, contour, harmony, texture; purely programmatic, evidence-cited |
| Fux species grader (species 1–5): pitch lists in, note-indexed rule violations out |
| Find harmonic features in 482 analyzed works — |
When a user shares a piece, these ground your feedback in evidence: the critique cites what it measured, the species grader points at the exact note, and the corpus search answers "show me a real example" with a citation.
Tool | What it does |
| Search the citable GVL-coded patterns — suspensions, cadences, the Rule of the Octave, sequences, part-writing norms — each with an authored realization and public-domain sources |
| Fetch one pattern by id or GVL code, with a ready-to-quote citation and related patterns |
The sibling of the Engraving Rulebook: where GE codes cover how music should
look on the page, GVL codes cover how voices should move. Every pattern cites
the public-domain treatise it rests on — Fux, Rameau, Kirnberger, Fenaroli,
Riepel, Prout — at chapter level, never through a modern edition, and the
realization.voices field is notation-API shorthand you can hand straight to
notation_render to engrave.
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: [...] }Tool | What it does |
| Search 166 original graded figured-bass exercises across seventeen stages — filter by stage, or search titles, concepts and GVL codes |
| Fetch one exercise by its permanent id, with the model realization, its teaching note, and the patterns it drills |
Where the Voice-Leading Reference states the rule, the corpus is the practice: a bass, its figures, and — unlike almost every surviving collection — a four-part model realization, machine-checked for voice leading. The stages run from root-position triads through the Rule of the Octave, cadence formulas, suspensions, the dominant seventh, sequences, minor mode, pedal point, the Riepel schemata, modulation and chromatic figures to unfigured bass and diminution.
Every exercise is original — nothing is transcribed from any edition — and the
whole corpus is CC BY 4.0. Exercise ids and stage slugs are permanent, so a
citation keeps resolving. givenBass is what you show the student;
realization is the answer to hold back until they have tried. Both are
notation-API shorthand, so either goes straight to 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 } }Pitches use scientific notation: C4, F#5, Bb3. Durations use letter codes: w h q 8 16 32 64 with optional . for dotted notes. Notes can be:
Shorthand: "C5/q" (quarter C5), "rest/q" (quarter rest), "[C4,E4,G4]/q" (chord)
Object form: { pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }
Bar lines are inferred from the time signature — write notes in time order and the API splits and ties anything that crosses a bar line.
{
"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"]
}]
}Env var | Default | Purpose |
|
| Override for self-hosted or local-dev API |
|
| Self-report your agent name in |
Free use is offered in exchange for crediting Gradus when you surface notation to your end user. Suggested wording (the API also returns this in every response):
Notation rendered by Gradus School of Music Composition (gradusmusic.com).
Full docs + Quick Start: https://gradusmusic.com/notation-api
OpenAPI 3.1 spec: https://gradusmusic.com/api-spec.yaml
JSON Schema for the input format: https://gradusmusic.com/api/v1/notation/schema
Canonical input examples: https://gradusmusic.com/api/v1/notation/examples
Agent-focused doc: https://gradusmusic.com/llms-api.txt
git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run buildTo smoke-test against the production API:
node test-client.mjsOpen an issue at https://github.com/delmas41/gradusnotation/issues. Contributions welcome — small, focused PRs preferred.
MIT — Sean Johnson, Gradus School of Music Composition. See LICENSE.
Search the Gradus music-theory knowledge base for authoritative source material. The corpus includes hand-authored curriculum prose, Bach chorale analysis (408 chorales), score commentaries on 50+ orchestral works, and primary historical sources from Fux (1725) through Boulanger.
WHEN TO USE: before generating notation if you need to look up a specific theory fact — typical voice leading for a Neapolitan-to-V resolution, idiomatic figured-bass realizations of a particular cadence, what makes a chromatic mediant feel like one composer's style versus another. Hitting this first prevents the agent from inventing chord progressions that are stylistically wrong.
WHEN NOT TO USE: for generic music vocabulary ("what is a chord?") that any LLM already knows; for non-theory queries like composer biographies, performance recommendations, or history dates — those are out of scope; for fetching actual score notation (use notation_render or notation_examples instead).
INPUT: provide EITHER topics (kebab-case tags) OR step (curriculum step 1-49). Topics are stronger; step is the fallback when you do not know the canonical topic tag. Both empty returns a MISSING_QUERY error.
OUTPUT (JSON): { ok: true, requestId, chunks: [{ id, sourceType, sourceId, title, content, composer?, era?, topics: string[], curriculumSteps: number[], tokenEstimate }], meta: { query, returnedCount, totalTokens, responseTimeMs }, attribution }. sourceType is one of: kg_concept, score_analysis, score_commentary, bach_chorale_analysis, composer, dictionary, curriculum, lesson_content, practicum, voice_leading, fugue, chorale_exercise, etc. Empty chunks: [] when nothing matched the topics — agent should fall back to its own knowledge or try a different topic tag.
EXAMPLE INPUT: { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } TYPICAL LATENCY: 200-700 ms (one Voyage 3 embedding call + Supabase pgvector RPC).
Inputs: topics, step, limit, maxTokens.
Fetch canonical example inputs (single melody, two-voice counterpoint, chord progression, mixed rhythms with dynamics, string quartet snippet, tied notes across bar lines). Cache the result client-side; the response shape is stable.
Inputs: no named parameters.
Render music notation from a JSON score. Returns inline SVG, MusicXML, and MIDI in one call. Use scientific pitches ("C4", "F#5", "Bb3") and duration codes (w h q 8 16 32 64 with optional dots). Bar lines are inferred from the time signature; notes that cross bar lines are split and tied automatically. Call notation_validate first if you are unsure your input is well-formed — validate is cheaper than render.
Inputs: instruments (required), title, composer, tempo, +2 more.
Fetch the JSON Schema for the notation_render input shape. Cache the result client-side; this is stable across the v1 API.
Inputs: no named parameters.
Pre-flight validate an input shape without rendering. Returns errors with concrete fix suggestions when input is malformed. Cheaper than notation_render — use this when iterating on input shape.
Inputs: instruments (required), title, composer, tempo, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool has a clearly distinct purpose: knowledge_search for theory facts, notation_examples for example inputs, notation_render for rendering, notation_schema for schema retrieval, and notation_validate for input validation. There is no functional overlap.
Tools use a mix of noun_verb (knowledge_search, notation_render, notation_validate) and noun_noun (notation_examples, notation_schema) patterns. Additionally, one tool deviates from the 'notation_' prefix ('knowledge_search'), reducing consistency.
With 5 tools, the server is reasonably scoped for its purpose of music notation rendering and theory knowledge retrieval. It covers core functionality without being overly minimal or excessive.
The tool set covers search, retrieval of examples, input validation, schema access, and rendering. Minor potential gaps (e.g., no tool to list available examples or manage rendered outputs) are not critical for the stated domain.
ScoreStarling is an all-in-one AI sheet music assistant. Ask for anything to do with sheet music: transcribe a song from audio, video or a link, read a PDF or photo, add chords, change the key, make it easier, turn it into guitar TAB or jianpu, or arrange it for another instrument. Every change lands on a real score you can hear, fix and download (PDF, MIDI, MusicXML, guitar TAB, jianpu, audio). Hosted remote server with OAuth sign-in. Free accounts get monthly credits and free previews; prices are at scorestarling.com/pricing. Setup: https://scorestarling.com/mcp
Convert MusicXML, MIDI, ABC, MEI and Humdrum, print sheet music, and verify every note survived.
Read-only sheet music discovery and practice tools, with browser-local recognition guidance.
Write lyrics in 100+ styles, score them, generate full songs with 4 engines, split stems. OAuth.
