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

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-mcpuv 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)