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/gradus (Next.js endpoint sources under app/api/v1/, MCP server under mcp/notation-server/)
JSON Schema: /api/v1/notation/schema
Examples: /api/v1/notation/examples
OpenAPI 3.1 spec: /api-spec.yaml
Agent-focused doc: /llms-api.txt