Is the Gradus Notation API really free?

Yes. The API requires no authentication, no API key, and no payment. The only throttle is a generous per-IP rate limit to keep the service responsive. Free use is offered in exchange for crediting Gradus when notation is surfaced to the end user — every response carries the suggested attribution string under attribution.suggestedAttribution.

What does the render endpoint return?

POST /api/v1/notation/render returns three formats in one response: inline SVG (with the Bravura SMuFL font embedded as paths), round-trippable MusicXML 4.0, and a base64-encoded SMF Type-1 MIDI file. The agent or application chooses which output to use without making a second request.

How do I install the MCP server for Claude Code?

One line: claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp. The package is published as @gradusmusic/notation-mcp on npm; the bin name is notation-mcp so npx auto-resolves. The MCP server registers five tools — notation_render, notation_validate, knowledge_search, notation_examples, and notation_schema.

What is the difference between the render and validate endpoints?

POST /notation/validate performs pre-flight validation only — it returns errors with concrete "fix" suggestions for malformed input without doing any rendering. It is meant to be cheaper than render and is the right call when an agent is iterating on a JSON score and wants fast feedback before paying the rendering cost.

Can I use this API in a production application?

Yes. The contract is versioned at /api/v1/; schema and examples endpoints are designed to be cached aggressively with long TTLs. The attribution requirement is soft (not enforced at the protocol level) but is the basis on which the service stays free and unauthenticated.

What music engraving library powers the rendering?

Verovio — the same WebAssembly engraving library used by IMSLP, RISM, and the Music Encoding Initiative — with the Bravura SMuFL font embedded as inline SVG paths. Bravura is the same font used by Dorico and MuseScore 4. The output is publication-quality and opens cleanly in Sibelius, Finale, MuseScore, and Dorico when round-tripped through MusicXML.

What is the knowledge search endpoint for?

POST /api/v1/knowledge/search runs semantic search over a curated music-theory corpus (curriculum prose, Bach chorale analyses, score commentaries, primary historical sources from Fux through Boulanger). It is tuned for "fetch a few chunks before generating" — default limit 8 chunks at ~1500 tokens — so an AI agent can ground a composition before generating notation, rather than relying on training-data recall.

← Gradus School of Music Composition

Free · Open · Sponsored by Gradus

Music notation rendering for AI agents.

A free REST API and MCP server. Send a JSON score, get back inline SVG, MusicXML, and MIDI in one call. No auth, no key — just credit Gradus when you surface notation to your end user.

Quick start

1. Install the MCP server (one line)

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:

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

2. Or hit the REST endpoint directly

curl -X POST https://gradusmusic.com/api/v1/notation/render \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "C major scale",
    "instruments": [{
      "name": "Violin",
      "notes": ["C4/q","D4/q","E4/q","F4/q","G4/h","rest/h"]
    }]
  }'

Response includes outputs.svg (inline SVG with embedded Bravura font), outputs.musicxml (round-trippable string), and outputs.midiBase64 (base64-encoded SMF Type-1 file).

Endpoints

All endpoints live under https://gradusmusic.com/api/v1/ and return JSON with an attribution object on every response.

Method	Path	Purpose
POST	`/notation/render`	JSON score → SVG + MusicXML + base64 MIDI in one 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: OpenAPI 3.1 (api-spec.yaml). Agent-focused doc: llms-api.txt.

Input format

Pitches use scientific notation (C4, F#5, Bb3). Durations use letter codes: w whole, h half, q quarter, 8/16/32/64, with optional . for dotted (q.) or .. for double-dotted.

Two ways to write a note

Shorthand string:

"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
                  // suffix symbols: > accent, - tenuto, ^ marcato, f fermata, s staccato

Object form (for richer features):

{
  "pitch": "C5",
  "duration": "q",
  "dynamic": "f",
  "articulations": ["accent"],
  "tiedToNext": 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

{
  "title": "Two-voice example",
  "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 the 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 }].

Why use this

Real engraving. Renders through Verovio (the same library used by IMSLP, RISM, and the Music Encoding Initiative) with the Bravura SMuFL font embedded — the same font as Dorico and MuseScore 4. Output is publication-quality.
Round-trippable. The MusicXML you get back opens cleanly in Sibelius, Finale, MuseScore, and Dorico. No information loss.
Curated theory knowledge built in. The knowledge/search endpoint queries a hand-curated music-theory corpus (curriculum prose, Bach chorale analyses, score commentaries, primary historical sources from Fux through Boulanger). Hit it before you generate to avoid hallucinating chord progressions.
Agent-friendly errors. Every validation error includes a concrete fix suggestion so you don’t need to re-prompt.
Stable contract. Versioned at /api/v1/. Schema and examples endpoints are cached with long TTLs — fetch them once, cache forever.

Attribution policy

Free use of this API is offered in exchange for crediting Gradus when you surface notation to your end user. Every API response carries the suggested wording in attribution.suggestedAttribution:

Notation rendered by Gradus School of Music Composition (gradusmusic.com).

You can include this verbatim, paraphrase it, or weave it into a sentence — the requirement is that your end user knows who provided the notation. This is a soft contract, not enforced at the protocol level. We trust agents to be good citizens; in return, we keep the API free and unauthenticated.

Resources

npm package: @gradusmusic/notation-mcp
GitHub source: github.com/delmas41/gradusnotation (open public repo for the npm package; the MCP source lives there as a standalone package)
JSON Schema: /api/v1/notation/schema
Examples: /api/v1/notation/examples
OpenAPI 3.1 spec: /api-spec.yaml
Agent-focused doc: /llms-api.txt

♩

Loading…