utau-lyrics
Generates UTAU/OpenUtau song files (.ust) with melodies fitted to a chord progression, plus a matching backing track.
create_song— lyrics + chords in,.ustfile and backing.mid/.wavof equal length out; options for key, tempo, instrument, style, drums, bass, voice range, guide flute volume, seed, soundfont.lyrics_to_ust— write only the.ust(no backing track), same arguments ascreate_song.render_backing— render just a backing.mid/.wavfrom chords, with optional bar count, instrument, style, drums, bass.preview_syllables— dry-run showing how each lyric line splits into notes (+= word continues,(xN)= held note) without generating files.list_options— list supported instruments, styles, lyric modes and chord qualities.
Note: it does not render the voice itself — you still open the .ust in UTAU/OpenUtau with a voicebank and import the .wav.
The backing track renderer can use the MuseScore_General SoundFont (an MIT-licensed .sf2 distributed by MuseScore) with FluidSynth to render the generated backing track with sampled General MIDI instruments instead of the built-in synth.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@utau-lyrics turn 'Twinkle, twinkle, little star' into a UST with chords C | G | Am | F"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
utau-lyrics-mcp
Test version. Give it lyrics and a chord progression, and it writes:
a
.ustfile for UTAU or OpenUtau, one note per syllable, with pitches chosen to fit the chordsa backing track of the same length as
.midand.wav, so the two line up at 0:00
It runs as an MCP server (for Claude or any other MCP client), as an OpenUtau or UTAU plugin, or from the command line.
It does not render the voice. You still open the .ust in UTAU or OpenUtau with a voicebank and import the backing .wav next to it.
Install
Python 3.10 or newer.
pip install -e .Related MCP server: midi-composer-mcp
Try it without an MCP client
python -m utau_lyrics_mcp song examples/lyrics_en.txt --chords "C | Am | F G | C" --output-dir outputThat writes output/lyrics_en.ust, output/lyrics_en_backing.mid and output/lyrics_en_backing.wav, and prints the melody it picked.
A Japanese voicebank needs kana lyrics. Write romaji and pass --lyric-mode romaji:
python -m utau_lyrics_mcp song examples/lyrics_romaji.txt --chords "Am | F | C | G" --key Am --lyric-mode romaji --instrument guitar --style strum --drums --output-dir outputUse it as an MCP server
Claude Code:
claude mcp add utau-lyrics -- python -m utau_lyrics_mcpClaude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"utau-lyrics": { "command": "python", "args": ["-m", "utau_lyrics_mcp"] }
}
}Files go to utau-lyrics-mcp-output in your user folder unless you pass output_dir or set UTAU_LYRICS_OUTPUT_DIR.
Tool | What it does |
| Lyrics and chords in, |
| The |
| A backing track from chords alone |
| Shows how each line will be split into notes |
| Instruments, styles, lyric modes, chord qualities |
Writing lyrics and chords
Each line of text is one sung line and gets two bars by default. A line with too many syllables takes more bars. A blank line is one bar of rest. The song starts with a one-bar intro and ends with one bar on the first chord of the progression.
English words are counted in syllables, one note each. The whole word goes on the first note and each later note gets +, so "window" becomes window +. OpenUtau's English phonemizers read that as "spread this word over these notes". For word fragments instead (win dow), use lyric_mode="syllables".
The syllable count is a rough guess based on vowel groups. It gets "window" and "little" right and counts "quiet" as one. Fix a word by hyphenating it yourself: qui-et, beau-ti-ful. Add ~ to hold a syllable longer: slow~. Run preview_syllables first to see the split.
Kana is split by mora. ー and っ lengthen the note before them.
Chords are bars separated by |. Chords inside one bar share it equally, and % repeats the previous bar:
C | Am | F G | %The progression loops until the lyrics run out. Supported qualities: major, m, 5, dim, aug, sus2, sus4, 6, m6, 7, maj7, m7, m7b5, dim7, 9, add9, plus slash bass like D/F#.
How the melody is chosen
Notes that start on a beat, and the last note of every line, use a tone from the chord playing at that moment. Notes between beats can use any note of the key. The picker prefers small steps from the previous note and stays inside voice_range (default A3-C5). The last note of the song lands on the tonic when the final chord contains it.
The same input always gives the same melody. Change seed for a different one.
The backing track and the voice
The backing has a chord part (block, strum or arpeggio), a bass, optional drums, and a flute that doubles the vocal melody quietly. The flute is there as a pitch reference while you tune the voice. Set guide_volume to 0 for a backing without it.
Instruments: piano, epiano, organ, guitar, strings, pad.
There are two renderers.
Built-in synth. Used by default. It builds each instrument from sine partials in numpy, so it needs no downloads and sounds like a synth.
FluidSynth with a SoundFont. For sampled instruments, install FluidSynth and get a free SoundFont such as FluidR3_GM (MIT), MuseScore_General (MIT) or GeneralUser GS (its own permissive licence). Then pass soundfont or set UTAU_LYRICS_SOUNDFONT to the .sf2 path. The instrument names map to General MIDI programs. If FluidSynth or the file is missing, the built-in synth takes over.
The .mid is always written, so you can also load it into any DAW and pick your own instruments.
Getting it to sing in OpenUtau
Open the .ust, pick a singer for the track, then pick a phonemizer that matches both the voicebank and the lyric language. A mismatch gives silence or a hum, and the log fills with "phonemizer error" lines.
English classic voicebank: use the phonemizer its readme names, usually
EN X-SAMPA,EN ARPA+orEN VCCV.Japanese voicebank: write the lyrics in kana or use
lyric_mode="romaji", with aJAphonemizer. A Japanese bank cannot sing English words.The
DiffSingerphonemizers only work with DiffSinger voicebanks.
Then import the backing .wav on a second track.
OpenUtau and UTAU plugin
Windows only for now.
python -m utau_lyrics_mcp install-pluginThis copies the plugin into OpenUtau's Plugins folder (Documents/OpenUtau/Plugins/utau-lyrics-mcp) and writes a run.bat that calls the Python you ran the command with. For classic UTAU, or an OpenUtau data folder somewhere else, pass the folder: --dir "C:\path o\plugins". Restart the editor afterwards.
In OpenUtau, select notes in the piano roll and pick "Fit notes to chords + backing track" from the legacy plugin menu. The plugin keeps your lyrics and note lengths, changes the pitches to fit the chords in settings.ini, and writes plugin_backing.wav and .mid for the selection to utau-lyrics-mcp-output in your user folder. Chords start at the first selected note.
Edit settings.ini in the installed folder to change chords, key, range, seed and instrument. Reinstalling keeps your settings.ini.
Not tested yet
The plugin has been run through its
run.baton a temp file in OpenUtau's format, but not from inside OpenUtau or UTAU.The FluidSynth path has not been run on a real install.
Rhythm is an even eighth-note grid. There is no syncopation and no melisma.
4/4 is the only time signature that has been tried, though
beats_per_barexists.
Tests
pip install -e ".[dev]"
pytestLicence
MIT
Available Tools
5 toolscreate_songA
Turn lyrics and a chord progression into a song: a UTAU .ust file plus a backing track (.mid and .wav) of the same length, so both line up at 0:00.
The vocal itself is not rendered here: open the .ust in UTAU or OpenUtau with a voicebank, and import the backing .wav alongside it.
lyrics: one sung line per text line; a blank line is a bar of rest. Write 'syl-la-ble' to force syllable breaks and 'la~' to hold a syllable. chords: bars separated by '|', e.g. 'C | Am | F G | C'. Chords in one bar share it equally, '%' repeats the previous bar. The progression loops. key: e.g. 'C', 'Bb', 'F#m'. Off-beat notes use this scale. lyric_mode: 'auto' (kana by mora; other words keep the whole word on their first note and '+' on the rest, which is what OpenUtau's English phonemizers expect), 'syllables' (word fragments like 'win' 'dow'), 'romaji' (convert romaji to hiragana for Japanese voicebanks), 'raw'. voice_range: lowest-highest note for the melody, e.g. 'A3-C5'. guide_volume: 0-1 level of a flute doubling the melody in the backing, as a pitch reference for the voice; 0 leaves it out. seed: change it to get a different melody over the same chords. soundfont: path to an .sf2 file; used if FluidSynth is installed, otherwise the built-in synth renders the backing.
Inputs: chords (required), lyrics (required), key, bass, +15 more.
list_optionsC
Instruments, accompaniment styles, lyric modes and chord qualities accepted.
Inputs: no named parameters.
lyrics_to_ustB
Write only the UTAU .ust file (melody fitted to the chords), no backing. Arguments are the same as create_song.
Inputs: chords (required), lyrics (required), key, name, +9 more.
preview_syllablesB
Show how each lyric line will be split into notes, before making a song. Notes are separated by spaces; '+' continues the word before it and '(xN)' marks a held note.
Inputs: lyrics (required), lyric_mode. Returns: result
render_backingC
Render only a backing track (.mid and .wav) from a chord progression. bars defaults to one pass through the progression.
Inputs: chords (required), bars, bass, name, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
create_song, lyrics_to_ust, and render_backing have intentional overlap (full song vs UST-only vs backing-only), but descriptions clearly state output boundaries. list_options and preview_syllables are distinct and unlikely to be confused.
Four tools follow a verb_noun snake_case pattern (list_options, create_song, render_backing, preview_syllables). lyrics_to_ust is noun_to_noun but stays in the same snake_case style and is unambiguous.
Five tools are well-scoped: option discovery, full song generation, two focused component generators, and a preview utility. No tool feels redundant or missing for the stated purpose.
The set covers option discovery, full song generation, UST-only generation, backing-only generation, and syllable preview. Vocal rendering is explicitly out of scope, so the missing capability is not a gap.
Maintenance
Related MCP Connectors
Write lyrics in 100+ styles, score them, generate full songs with 4 engines, split stems. OAuth.
ACE Music: songs from a prompt or your lyrics, covers, remixes, mashups, stems, scores, MIDI
AI music studio: song generation with vocals, covers, stems, voice conversion, mastering, editing.
Make songs, change one part's lyrics in the same voice, and reimagine songs in new styles.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI-driven MIDI composition with chord name support, interactive piano-roll preview, and multiple deployment modes.258MIT
- AlicenseAqualityBmaintenanceProvides atomic music-theory and MIDI tools for composing, enabling LLMs to chain deterministic steps like scale/chord lookups, degree resolution, rhythm generation, and MIDI rendering.131MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to generate, inspect, and micro-tune OpenUtau .ustx project files and DiffSinger neural expression curves.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables local AI-assisted tuning of Synthesizer V Studio 2 Pro projects via natural language, providing tools for reading selections, previewing and applying parameter adjustments, recording and comparing audio, and managing sessions.1MIT