delmas41/gradusnotation

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.
Why
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.
Install
In Claude Code:
In Claude Desktop, add to your MCP config:
Tools
Gradus Notation
| Tool | What it does |
|---|---|
| notation_render | JSON score → SVG + MusicXML + MIDI in one call |
| notation_validate | Pre-flight validate input shape (cheaper than render) |
| knowledge_search | Look up music-theory chunks before generating notation |
| notation_examples | Canonical input examples (cache and reuse) |
| notation_schema | JSON Schema for the input shape (cache and reuse) |
Gradus Harmonic Analyzer
Four new tools backed by the native TypeScript MaestroAnalyzer engine — no music21 dependency, no Python, no extra server.
| Tool | What it does |
|---|---|
| theory_analyze_score | Parse MusicXML → full harmonic analysis + GKB knowledge chunks in one call |
| theory_parse_xml | Parse a MusicXML string → maestroAnalyst Score JSON |
| theory_validate_ranges | Check every note in a Score against its instrument's practical range |
| theory_respell | Suggest preferred enharmonic spelling for pitches in a key context |
| theory_pitch_utils | Pure-function pitch arithmetic: midi_to_pitch, pitch_to_midi, interval_name, transpose_pitch |
**Typical workflows:**
Gradus Engraver — checks against the Gradus Engraving Rulebook
| Tool | What it does |
|---|---|
| engraving_rules | Search 423 sourced music-engraving rules by text, domain, severity, or how they are checked |
| engraving_rule | Fetch one rule by its permanent id, with a ready-to-quote citation and related rules |
| engraving_check | 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