# Gradus Music Notation API > Free, open music notation API and Model Context Protocol (MCP) server. Any AI agent can render music notation from a JSON score, validate input, and search a curated music-theory knowledge base. No auth, no API key, no rate limit beyond a generous per-IP cap. Sponsored by Gradus School of Music Composition (gradusmusic.com). ## Quick install (MCP — recommended) For Claude Code: ``` claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp ``` For Claude Desktop, Cursor, or any MCP client, add to the config: ```json { "mcpServers": { "gradus-notation": { "command": "npx", "args": ["-y", "@gradusmusic/notation-mcp"] } } } ``` The MCP server registers five tools: `notation_render`, `notation_validate`, `knowledge_search`, `notation_examples`, `notation_schema`. Tool descriptions live inside the server (under 500 tokens total) so the agent reads them on connect. ## REST endpoints All endpoints live under `https://gradusmusic.com/api/v1/`. Every response includes an `attribution` object with the suggested credit line. | Method | Path | Purpose | | --- | --- | --- | | POST | `/notation/render` | JSON score → inline SVG, MusicXML, base64 MIDI in a single response | | POST | `/notation/validate` | Pre-flight validation. Returns errors with concrete `fix` suggestions, no rendering cost | | POST | `/knowledge/search` | Semantic search over the Gradus music-theory knowledge base by topic tags or curriculum step | | GET | `/notation/schema` | JSON Schema for the input shape. Cache aggressively — stable across the v1 API | | GET | `/notation/examples` | Six canonical input examples (melody, counterpoint, chord progression, mixed rhythms, string quartet, tied notes) | Machine-readable spec: [https://gradusmusic.com/api-spec.yaml](https://gradusmusic.com/api-spec.yaml) ## Input format Pitches use scientific notation (`C4`, `F#5`, `Bb3`). Durations use letter codes: - `w` whole, `h` half, `q` quarter, `8`, `16`, `32`, `64` - Add `.` for a dotted note (`q.` = dotted quarter), or `..` for double-dotted Two ways to write a note: **Shorthand string** (one note): ``` "C5/q" // quarter C5 "F#4/h" // half F-sharp 4 "Bb3/q." // dotted quarter B-flat 3 "rest/q" // quarter rest "[C4,E4,G4]/q" // quarter C-major triad chord "C5/q>" // quarter C5 with accent ``` Articulation symbols append after the duration: `>` accent, `-` tenuto, `^` marcato, `f` fermata, `s` staccato. **Object form** (richer features): ```json { "pitch": "C5", "duration": "q", "dynamic": "f", "articulations": ["accent"], "tiedToNext": true } ``` For chords use `pitches: ["C4","E4","G4"]`. For rests use `rest: true`. ## Bar lines are inferred Notes are written in time order; bar lines are inferred from the time signature. A note that crosses a bar line is split and tied automatically. You don't count beats per measure. ## Multi-instrument and multi-voice ```json { "title": "Two-voice example", "tempo": 100, "timeSignature": [4, 4], "keySignature": "G major", "instruments": [ { "name": "Violin", "notes": ["G4/q","A4/q","B4/q","C5/q"] }, { "name": "Cello", "notes": ["G3/h", "D4/h"] } ] } ``` Clefs are inferred from instrument name (Cello → bass, Viola → alto, Timpani → percussion). Override with the optional `clef` field. For multiple voices on a single staff, replace `notes` with `voices: [{ voice: 1, notes }, { voice: 2, notes }]`. ## Example render call ``` POST https://gradusmusic.com/api/v1/notation/render Content-Type: application/json { "title": "C major scale", "instruments": [{ "name": "Violin", "notes": ["C4/q","D4/q","E4/q","F4/q","G4/h","rest/h"] }] } ``` Response: ```json { "ok": true, "requestId": "uuid-...", "outputs": { "svg": "...", "musicxml": "...", "midiBase64": "TVRoZAAAAAYAAQA..." }, "meta": { "measureCount": 1, "instrumentCount": 1, "voiceCount": 1, "durationBeats": 4, "renderTimeMs": 859 }, "attribution": { "sponsor": "Gradus School of Music Composition", "url": "https://gradusmusic.com", "suggestedAttribution": "Notation rendered by Gradus School of Music Composition (gradusmusic.com).", "apiVersion": "v1" } } ``` ## Error format Validation errors include a concrete `fix` suggestion so you don't need to re-prompt the user: ```json { "ok": false, "requestId": "uuid-...", "errors": [{ "path": "instruments[0].voices[0].notes[0]", "code": "BAD_PITCH", "severity": "error", "message": "Invalid pitch \"X9\" in \"X9/q\".", "fix": "Use scientific notation: letter A-G + optional # or b + octave number, e.g. \"C4\", \"F#5\", \"Bb3\"." }], "attribution": { ... } } ``` ## Knowledge search Look up music-theory facts before generating notation. Returns ranked chunks from the curated Gradus knowledge base (curriculum prose, Bach chorale analyses, score commentaries, primary historical sources from Fux through Boulanger). ``` POST https://gradusmusic.com/api/v1/knowledge/search Content-Type: application/json { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } ``` Or by curriculum step: ``` { "step": 22, "limit": 3 } ``` ## Attribution policy Free use is offered in exchange for crediting Gradus when you surface notation to your end user. Every API response carries the wording in `attribution.suggestedAttribution`: > Notation rendered by Gradus School of Music Composition (gradusmusic.com). Include verbatim, paraphrase, or weave into a sentence — the requirement is that the end user knows who provided the notation. ## Resources - [Documentation page](https://gradusmusic.com/notation-api) - [npm package](https://www.npmjs.com/package/@gradusmusic/notation-mcp) - [GitHub source](https://github.com/delmas41/gradus) - [JSON Schema](https://gradusmusic.com/api/v1/notation/schema) - [Canonical examples](https://gradusmusic.com/api/v1/notation/examples) - [OpenAPI 3.1 spec](https://gradusmusic.com/api-spec.yaml) ## About the sponsor Gradus is an online conservatory teaching composition the way it was learned for centuries — species counterpoint, figured bass, chorale harmonization, era by era from Fux through Boulanger. Visit [gradusmusic.com](https://gradusmusic.com).