@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.