Purpose
Gradus Notation is a music notation toolset for AI agents, provided as an MCP server and REST API. It lets agents submit JSON scores without a graphical interface and obtain inline SVG, MusicXML, and MIDI output in a single call. The tool is sponsored by Gradus (a music composition course for homeschooling, gradusmusic.com) and is a general-purpose developer tool; it is not the course itself and is not limited to educational use. Target users include composition assistants, musicology and corpus research, theory Q&A that needs rendered examples, MIDI pipelines, engraving quality checks, and any agent or application involving music, such as games and documentation.
Main capabilities
A single installation includes three named tools:
- Gradus Notation: Renders JSON scores as inline SVG, MusicXML, and MIDI, and provides preflight validation (notation_render, notation_validate).
- Gradus Harmonic Analyzer: Full-score analysis covering Roman numerals, key and modulation, cadences, pedal points, and texture, powered by the native TypeScript MaestroAnalyzer engine, with no music21 dependency, no Python or additional server required, providing theory_analyze_score and theory_* tools, and with the standalone TypeScript library gradus-analyst published on npm.
- Gradus Engraver: Checks score engraving according to the citable GE-coded rules in the Gradus engraving rulebook (engraving_check). Each rule distinguishes convention (the rule itself), authority (what treatises say, cited to chapter, and citing only public-domain treatises such as Fux, Rameau, Kirnberger, Fenaroli, Riepel, Prout), and internal ruling (Gradus's choice when sources disagree). Rule IDs are permanent, rule text is licensed CC BY 4.0, and the citation field may be cited. An invalid error ID returns 404 along with the nearest matching IDs, making it possible to correct within a single call.
It also provides pitch tools, range validation, enharmonic respelling, and an engraving [section] containing 444 rules.notation checker. The Gradus voice-leading reference (GVL encoding) provides chapter-level citations for each mode from public-domain treatises, and its realization.voices field can be handed directly to notation_render for engraving. The Gradus figured-bass corpus contains bass, figures, and four-voice model realizations (machine-checked voice leading), covering stages from root-position triads through the octave rule, cadential formulas, suspensions, dominant sevenths, sequences, minor mode, pedal points, Riepel schemata, modulation and chromaticism, unfigured bass, and diminution. All exercises are original, the corpus is licensed CC BY 4.0, exercise IDs and stage slugs are permanently valid; givenBass is what is shown to the student, realization is the retained answer.
How to use
Install in Claude Code; add it to the MCP configuration in Claude Desktop. Free to use with no authentication and no API key. Building a local version allows smoke testing against the production API. The engraving_check closed loop is: generate notation, check, fix the discovered issues. Prefer passing local file paths, which the server reads directly, so scores need not pass through the model context as base64. Before trusting an empty findings list, read coverage.unchecked, which lists what the checker cannot verify.
Pitches use scientific pitch notation (C4, F#5, Bb3), and durations use letter codes (w h q 8 16 32 64, optionally with . for dotted). Notes can be written in shorthand (e.g. "C5/q", "rest/q", "[C4,E4,G4]/q") or in object form (e.g. { pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }). Barlines are inferred from the time signature; write notes in chronological order, and the API will split and tie notes across barlines.
Free use requires crediting Gradus when displaying notation to end users; the suggested wording (also returned with every response) is: Notation rendered by Gradus School of Music Composition (gradusmusic.com).
When it applies
Composition assistants, musicology and corpus research, theory Q&A that needs rendered examples, MIDI pipelines, engraving quality checks, games, documentation, and any agent or application involving music processing. When a user shares a work, these tools let feedback be grounded: comments cite what was measured, type scores point to specific notes, and corpus searches answer "give me a real example" with citations.
Limitations
- This tool is a general developer tool, not the Gradus course itself.
- Engraving checks depend on the rulebook; what is listed in coverage.unchecked cannot be verified.
- The free tier requires crediting Gradus.
- Other limitations are not yet provided.
Documentation and resources
Full documentation and quick start:https://gradusmusic.com/notation-api OpenAPI 3.1 specification:https://gradusmusic.com/api-spec.yaml Input format JSON Schema:https://gradusmusic.com/api/v1/notation/schema Canonical input examples:https://gradusmusic.com/api/v1/notation/examples Agent-facing documentation:https://gradusmusic.com/llms-api.txt Questions and contributions:https://github.com/delmas41/gradusnotation/issues License: MIT, author Sean Johnson, Gradus School of Music Composition.
