lilypond-mcp
Engrave LilyPond music sources into cropped, placeable assets (PDF, EPS, SVG, PNG) entirely locally via a bundled WebAssembly engine.
engrave_file — engrave a
.lysource file into publication-quality notation assets; defaults to cropped PDF (InDesign-ready with all PDF boxes defined) plus an inline preview PNG.engrave_code — engrave LilyPond code inline without touching disk, ideal for iterating on a musical idea (defaults to PNG).
lilypond_version — report the LilyPond version the server engraves with, for choosing the right
\versionheader.Choose output formats (
pdf/eps/svg/png), toggle crop to size to the music, and set output_dir.Resolve shared
\includelibraries via include_dirs.Get inline preview PNGs to see the result without reading files (disable for batch runs).
Receive LilyPond diagnostics with line numbers on failure so sources can be fixed and retried.
Works fully offline and privately (desktop extension bundles the engine; no telemetry).
Engraves GNU LilyPond music notation sources into cropped PDF, EPS, SVG, and PNG assets, including preview images and diagnostics for iterating on scores.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lilypond-mcp Engrave melody.ly to cropped SVG and PNG"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lilypond-mcp
MCP server that engraves GNU LilyPond sources into placeable assets: cropped PDF, EPS, SVG, and PNG, sized to the music rather than a full page — ready to drop into page-layout software such as InDesign.
Nothing to install beyond Node: the server fetches a WebAssembly build of LilyPond on first use and engraves with that — the same engine on every machine.
Quick start
Claude Code — .mcp.json in your project:
{
"mcpServers": {
"lilypond": {
"command": "npx",
"args": ["-y", "lilypond-mcp@latest"]
}
}
}Claude Desktop — claude_desktop_config.json, same entry under
mcpServers. Or skip the config entirely: grab the .mcpb file from
the latest release
and open it with Claude Desktop — a desktop extension with the engine
bundled in, so it works offline from the first engrave.
That's the whole setup. On the first engrave, the server downloads the
engine (~35 MB, checksum-verified, cached under
~/.cache/lilypond-mcp — safe to delete at any time).
Related MCP server: inkscape-mcp-server
Tools
engrave_file— engrave a.lyfile. Defaults to cropped PDF — the format to place in InDesign (fonts embedded and subsetted, all PDF boxes defined). Also returns a preview PNG, both as a file and inline as an image in the tool result, so the agent sees what it engraved.engrave_code— engrave LilyPond code passed inline, for iterating on a musical idea without touching disk.lilypond_version— the LilyPond version the server engraves with, for picking the right\versionheader.
Both engrave tools accept formats (pdf/eps/svg/png), crop,
include_dirs (for shared \include libraries), output_dir, and
preview (default on; turn off to skip the inline image on batch runs). Paths
are resolved against the working directory the server is launched in — for
an .mcp.json entry, that is the project root. On failure the result
carries LilyPond's diagnostics, line numbers included, so an agent can fix
the source and retry.
What you get
This snippet, sent to engrave_code:
\version "2.26.0"
\header { tagline = ##f }
\score {
<<
\new ChordNames \chordmode { g2. | c | d | g }
\new Staff \new Voice = "m" \relative c'' {
\key g \major
\time 3/4
\tempo "Waltz" 4 = 132
g4 b d | e4.( d8) c4 | a4 fis d | g2 r4 \bar "|."
}
\new Lyrics \lyricsto "m" { Round and round the waltz goes, old and slow. }
>>
\layout { indent = 0 }
}comes back cropped to the music, as PDF, EPS, SVG or PNG — this is the SVG:
(Source in docs/example.ly.)
Engine
Engraving runs a WebAssembly build of LilyPond from
lilypond-wasi releases,
pinned in engine.json and executed in a child Node process via
node:wasi. Node 22 or newer: the engine uses WebAssembly exception
handling that V8 first shipped in Node 22. (The node:wasi fast-call
regression in Node 22.21.1+ —
nodejs/node#59600 — is
sidestepped automatically with --no-turbo-fast-api-calls.)
The engine trails lilypond-wasi's stable releases: a weekly workflow
re-pins engine.json to the newest release, engraves with it as a real
consumer, and opens a PR.
Development
npm install
npm run build # tsc → dist/
npm test # engraves real snippets with the wasm engine** The tests need an engine dir and skip without one. Either download the
pinned release into the cache — node scripts/assemble-engine-dir.mjs
prints the dir — or build one from a lilypond-wasi checkout:
./test/assemble-engine-dir.sh /tmp/engine-dir ../lilypond-wasi stable.
Then LILYPOND_MCP_ENGINE_DIR=<dir> npm test.
Releases: conventional commits → Knope bot release PR → merge → npm publish via OIDC trusted publishing (no tokens).
Privacy Policy
Everything happens on your machine. LilyPond sources are engraved locally by the bundled WebAssembly engine; neither your sources nor the generated assets ever leave your computer, and the server collects no data — no telemetry, no analytics, no accounts.
The npm package makes exactly one kind of network request: downloading
the pinned engine release from GitHub on first use (verified against
checksums, cached under ~/.cache/lilypond-mcp). The desktop extension
(.mcpb) ships the engine inside the bundle and makes no network
requests at all.
Generated assets are written to the output_dir you choose and stay
under your control; the server retains nothing else. Questions:
wilfred@eastpole.nl or the
issue tracker.
Licence
MIT. The server runs a GPL-licensed engraver (the lilypond-wasi
WebAssembly build of GNU LilyPond) as a separate program, and the npm
package contains none of its bytes — see
LICENSING.md for the analysis and the design rules that keep that
boundary clean.
Available Tools
3 toolsengrave_codeEngrave LilyPond CodeAIdempotent
Engrave LilyPond code passed inline, without needing a source file on disk. Useful for iterating on a musical idea: engrave, read the preview PNG, adjust, repeat. For anything worth keeping, write a .ly file and use engrave_file instead.
Inputs: code (required), crop, name, formats, +3 more. Returns: ok, errors, outputs, previewPng
engrave_fileEngrave LilyPond FileAIdempotent
Engrave a LilyPond (.ly) source file into publication-quality music notation assets. Cropped assets are sized to the music, ready to place in page-layout software. Use PDF for InDesign placement (fonts embedded the way Adobe accepts, crop/bleed/trim/art boxes all defined); SVG has glyphs as outlines for the web; EPS embeds fonts in a form Ghostscript accepts but InDesign ignores. On failure, errors carries the LilyPond diagnostics, including line numbers.
Inputs: source (required), crop, name, formats, +3 more. Returns: ok, errors, outputs, previewPng
lilypond_versionLilyPond VersionARead-only
Report the LilyPond version this server engraves with. Use it to pick the right \version header for new .ly files.
Inputs: no named parameters. Returns: version
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have clearly distinct purposes: engrave_file operates on a .ly path, engrave_code takes inline source, and lilypond_version reports the engine version. The descriptions explicitly contrast the two engrave tools, reducing any misselection risk.
engrave_file and engrave_code share a consistent verb_noun pattern, but lilypond_version breaks it with a noun_noun form. The deviation is minor and still readable as a cohesive set.
Three tools is a tight, focused scope appropriate for a single-purpose LilyPond engraver wrapper. It's on the lean side but each tool earns its place without redundancy.
Core workflow (engrave file, engrave inline, check version) is fully covered with no dead ends for typical use. A preview/validate-only or batch operation is absent, but agents can work around this via engrave_code plus engrave_file.
Maintenance
Related MCP Connectors
Convert MusicXML, MIDI, ABC, MEI and Humdrum, print sheet music, and verify every note survived.
Generate and vectorize clean, editable SVG graphics from text, images, or both.
Floor plans as code: compile, lint and repair ArchLang (.arch) floor plans to SVG, DXF and PDF.
Compile LaTeX to PDF without installing TeX Live. No API key needed to start.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables headless and secure control of Inkscape for creating, inspecting, and resizing SVG documents, and exporting to PNG, PDF, and SVG with validation of size, pages, structure, and hashes.90MIT
- AlicenseBqualityBmaintenanceEnables driving Inkscape headlessly from an MCP client, with verified SVG editing, rendering, optimization, and animation tools.23MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to create, inspect, edit, render, and export SVG/Inkscape documents through typed drawing tools, with a deterministic offline backend and an optional bridge to a locally running Inkscape instance for limited live editing and snapshots.5BSD 3-Clause
- AlicenseAqualityBmaintenanceEnables AI clients to generate and edit MuseScore scores from compact text notation and export them as mscz, PDF, PNG, SVG, MIDI, or MP3 without opening the MuseScore GUI.11MIT