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": "<score-partwise>...</score-partwise>"}}

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

// Synthesize Soprano part only at 80% tempo
{
  "tool": "synthesize",
  "arguments": {
    "musicxml": "<score-partwise>...</score-partwise>",
    "output_path": "/tmp/soprano.wav",
    "part_ids": ["Soprano"],
    "tempo_factor": 0.8
  }
}

Note: part_ids are the part names returned by get_parts (e.g. "Soprano", "Alto"), not XML <part id>-style values like "P1" — music21 uses the part name as its id.

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

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