@gradusmusic/notation-mcp

Model Context Protocol server for the Gradus Notation API. Lets AI agents render music notation, validate input, and search a curated music-theory knowledge base — sponsored by Gradus School of Music Composition.

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.

Install

In Claude Code:

claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp

In Claude Desktop, add to your MCP config:

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

Tools

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)

Input format

Pitches use scientific notation: C4, F#5, Bb3. Durations use letter codes: w h q 8 16 32 64 with optional . for dotted notes. Notes can be:

Shorthand: "C5/q" (quarter C5), "rest/q" (quarter rest), "[C4,E4,G4]/q" (chord)
Object form: { pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }

Bar lines are inferred from the time signature — write notes in time order and the API splits and ties anything that crosses a bar line.

Example

{
  "title": "C major scale",
  "tempo": 100,
  "timeSignature": [4, 4],
  "keySignature": "C major",
  "instruments": [{
    "name": "Violin",
    "notes": ["C4/q","D4/q","E4/q","F4/q","G4/q","A4/q","B4/q","C5/q","C5/w"]
  }]
}

Configuration

Env var	Default	Purpose
`GRADUS_NOTATION_API_BASE`	`https://gradusmusic.com`	Override for self-hosted or local-dev API
`GRADUS_AGENT_NAME`	`@gradusmusic/notation-mcp`	Self-report your agent name in `X-Agent-Name` header

Attribution

Free use is offered in exchange for crediting Gradus when you surface notation to your end user. Suggested wording (the API also returns this in every response):

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

Documentation

Full docs + Quick Start: https://gradusmusic.com/notation-api
OpenAPI 3.1 spec: https://gradusmusic.com/api-spec.yaml
JSON Schema for the input format: https://gradusmusic.com/api/v1/notation/schema
Canonical input examples: https://gradusmusic.com/api/v1/notation/examples
Agent-focused doc: https://gradusmusic.com/llms-api.txt

Building locally

git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run build

To smoke-test against the production API:

node test-client.mjs

Issues + contributions

Open an issue at https://github.com/delmas41/gradusnotation/issues. Contributions welcome — small, focused PRs preferred.

License

MIT — Sean Johnson, Gradus School of Music Composition. See LICENSE.

notation-mcp