MusicXML Renderer

render-mcp

可将 MusicXML 乐谱渲染为 PDF 或 PNG 图像的 MCP 服务。

功能

接收 MusicXML 文档，并生成适合打印的 PDF 或适合屏幕显示的 PNG 图像。使用 Verovio 进行排版和制谱，无需外部工具或 GUI。

工具

工具	描述
render_to_pdf	将完整乐谱渲染为多页 PDF 文件
render_to_image	将单页渲染为 PNG 或 SVG
list_capabilities	返回服务元数据：后端版本、支持的格式和可用的渲染器
health_check	检查所有运行时依赖项是否可用，以及服务是否已准备好渲染乐谱

安装

快速安装：运行 ./install.sh，一键完成设置；也可参阅 SETUP.md 中的非技术人员指南。预先配置好的客户端配置（Claude Desktop、Cursor、Windsurf、Continue、Zed）位于 examples/。如果遇到问题，请查看 TROUBLESHOOTING.md。

手动设置：

cd render-mcp
uv sync

PNG 输出需要 libcairo：

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

运行

uv run render-mcp

无需设置环境变量。

使用示例

// 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 范围：72–600。默认值：150。页码从 1 开始。

measures: [start, end]（可选，两个工具均支持）仅渲染指定的印刷小节；弱起小节的编号为 0。 截取的乐谱会保留 start 处生效的调号、拍号和谱号。measures 范围颠倒或超出范围时，会报出 INVALID_PARAMETER 错误，其 hint 会指出乐谱的第一个和最后一个小节。

请通过 musicxml_path（.musicxml、.xml 或 .mxl）提供乐谱，或将其内联为 musicxml，不能同时使用两者。路径必须位于 SHEET_MUSIC_OUTPUT_ROOT（默认值：工作目录）、客户端的某个根目录，或 SHEET_MUSIC_INPUT_ROOTS 中列出的文件夹内；output_path 必须位于 SHEET_MUSIC_OUTPUT_ROOT 内。describe_score 可在不进行渲染的情况下返回乐谱的声部（ID 为 P1 …）、调号、拍号、速度和长度。

测试

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

依赖项

• verovio — 将 MusicXML 制作为 SVG（纯 Python，在进程内运行）
• cairosvg — 将 SVG 转换为 PNG/PDF
• pypdf — 组装多页 PDF
• Pillow — 图像实用工具
• mcp — MCP 协议

系统要求

• Python 3.11+
• libcairo2 共享库（供 cairosvg 输出 PNG/PDF）