MusicXML Renderer

render-mcp

MCP server that renders MusicXML scores to PDF or PNG images.

What it does

Takes a MusicXML document and produces print-ready PDFs or screen-ready PNG images. Uses Verovio for layout and engraving — no external tools or GUI required.

Tools

Tool	Description
render_to_pdf	Render the full score to a multi-page PDF file
render_to_image	Render a single page to PNG or SVG
list_capabilities	Return server metadata: backend version, supported formats, available renderers
health_check	Check whether all runtime dependencies are available and the server is ready to render scores

Installation

Quick install: run ./install.sh for one-command setup, or see SETUP.md for a non-technical walkthrough. Ready-made client configs (Claude Desktop, Cursor, Windsurf, Continue, Zed) are in examples/. If something isn't working, check TROUBLESHOOTING.md.

Manual setup:

cd render-mcp
uv sync

libcairo is required for PNG output:

# Ubuntu / Debian (usually pre-installed on desktop systems)
sudo apt install libcairo2

Running

uv run render-mcp

No environment variables required.

Usage examples

// Render full score to PDF
{
  "tool": "render_to_pdf",
  "arguments": {
    "musicxml_path": "/path/to/score.mxl",
    "output_path": "/tmp/score.pdf"
  }
}

// Render page 1 to PNG at 150 DPI
{
  "tool": "render_to_image",
  "arguments": {
    "musicxml_path": "/path/to/score.mxl",
    "output_path": "/tmp/page1.png",
    "page": 1,
    "dpi": 150
  }
}

// Render only bars 17–24 (printed measure numbers, inclusive) to PDF
{
  "tool": "render_to_pdf",
  "arguments": {
    "musicxml_path": "/path/to/score.mxl",
    "measures": [17, 24]
  }
}

DPI range: 72–600. Default: 150. Page numbers are 1-indexed.

measures: [start, end] (optional, both tools) renders only those printed bars; a pickup bar is 0. The cut score keeps the key, time and clef in force at start. A reversed or out-of-range measures is an INVALID_PARAMETER error whose hint names the score's first and last bars.

Give the score as musicxml_path (.musicxml, .xml or .mxl) or inline as musicxml, not both. A path must lie inside SHEET_MUSIC_OUTPUT_ROOT (default: the working directory), one of the client's roots, or a folder listed in SHEET_MUSIC_INPUT_ROOTS; output_path must lie inside SHEET_MUSIC_OUTPUT_ROOT. describe_score returns a score's parts (IDs P1 …), key, time, tempo and length without rendering it.

Testing

# All tests including integration (Verovio runs in-process, no external tool needed)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v

Dependencies

• verovio — MusicXML engraving to SVG (pure Python, in-process)
• cairosvg — SVG to PNG/PDF conversion
• pypdf — multi-page PDF assembly
• Pillow — image utilities
• mcp — MCP protocol

System requirements

• Python 3.11+
• libcairo2 shared library (for PNG/PDF output via cairosvg)