MusicXML Renderer

render-mcp

MusicXML 楽譜を PDF または PNG 画像にレンダリングする MCP サーバーです。

機能

MusicXML ドキュメントを受け取り、印刷に適した PDF または画面表示に適した PNG 画像を生成します。レイアウトと浄書には Verovio を使用するため、外部ツールや GUI は不要です。

ツール

ツール	説明
render_to_pdf	楽譜全体を複数ページの PDF ファイルにレンダリングします
render_to_image	1 ページを 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 出力に必要）