MusicXML Synthesizer

synth-mcp

MCP server that synthesizes audio from MusicXML. Supports voice part selection (Soprano, Alto, Tenor, Bass) and tempo control.

What it does

Takes a MusicXML score, optionally filters to one or more voice parts, and renders a WAV audio file using FluidSynth. Useful for choir singers who want to practice a specific voice part.

Tools

Installation

cd synth-mcp

uv sync

System library required:

# Ubuntu / Debian

sudo apt install libfluidsynth-dev

macOS

brew install fluid-synth

A soundfont (SF2) file is also required. Free options:

Quick install

Prefer not to do the above by hand? Run ./install.sh — it installs uv, the system libfluidsynth package, and a soundfont automatically. See SETUP.md for a non-technical walkthrough, and TROUBLESHOOTING.md if something goes wrong. Ready-made client configs (Claude Desktop, Cursor, Windsurf, Continue, Zed) are in examples/.

Running

SYNTH_SOUNDFONT_PATH=/usr/share/sounds/sf2/TimGM6mb.sf2 uv run synth-mcp

Configuration

Claude Desktop configuration

{

"mcpServers": { "synth": { "command": "uv", "args": ["--directory", "/absolute/path/to/synth-mcp", "run", "synth-mcp"], "env": { "SYNTH_SOUNDFONT_PATH": "/absolute/path/to/soundfont.sf2" } } } }

Usage examples

// List parts in a score

{"tool": "get_parts", "arguments": {"musicxml": " ... "}}

// The same, reading a file instead of copying the score into the conversation {"tool": "get_parts", "arguments": {"musicxml_path": "scores/chorale.mxl"}}

// Synthesize the full score { "tool": "synthesize", "arguments": { "musicxml": " ... ", "output_path": "/tmp/full.wav" } }

// Synthesize Soprano part only at 80% tempo { "tool": "synthesize", "arguments": { "musicxml": " ... ", "output_path": "/tmp/soprano.wav", "parts": ["Soprano"], "tempo_factor": 0.8 } }

// Practice track: Alto loud, others soft, bars 17-24 three times, one bar of count-in { "tool": "synthesize", "arguments": { "musicxml_path": "scores/chorale.mxl", "preset": "learning", "focus_part": "Alto", "measures": [17, 24], "repeat": 3, "count_in_bars": 1 } }

// Starting notes before singing {"tool": "starting_pitches", "arguments": {"musicxml_path": "scores/chorale.mxl"}}

parts accepts part IDs from get_parts ("P1"), part names ("Soprano", any case) or voices ("S", "Alto", "Alt", "A1" for divisi); an unknown part returns the valid choices. part_ids still works as a deprecated alias for one minor release.

Every tool that takes musicxml also takes musicxml_path instead (exactly one of the two): a .musicxml, .xml or compressed .mxl file inside the output root, a folder the client shares as an MCP root, or a folder in SHEET_MUSIC_INPUT_ROOTS. Prefer it, and pass on paths other servers return. describe_score reports part IDs, ranges and duration without returning the score.

tempo_factor range: 0.25–4.0. Values below 1.0 slow down; above 1.0 speed up. Does not affect pitch.

Practice options on synthesize (all optional; leaving them out gives the plain track):

starting_pitches returns the text always; the clip (mono 16 kHz WAV, inline when ≤ 200 KB) needs the soundfont and FluidSynth. Without them the result says why in audio_unavailable.

Testing

# Unit tests (no soundfont required)

VIRTUAL_ENV= .venv/bin/pytest tests/ -v

Integration tests (synthesizes real audio)

VIRTUAL_ENV= SYNTH_SOUNDFONT_PATH=/usr/share/sounds/sf2/TimGM6mb.sf2 \ .venv/bin/pytest tests/ -v -m integration

Dependencies

• music21 — score parsing and MIDI export
• pyfluidsynth — Python bindings for FluidSynth
• mcp — MCP protocol

Known limitations

• music21's MIDI export may drop some articulations and dynamics
• Audio output is always WAV; convert with ffmpeg -i out.wav out.mp3 if needed
• Large scores (100+ measures) may take several seconds to synthesize

System requirements

• Python 3.11+
• libfluidsynth shared library (libfluidsynth.so.3 on Linux)
• An SF2 soundfont file