Skip to main content
Glama

utau-lyrics-mcp

license release made with MCP Ko-fi Linktree

Test version. Give it lyrics and a chord progression, and it writes:

  • a .ust file for UTAU or OpenUtau, one note per syllable, with pitches chosen to fit the chords

  • a backing track of the same length as .mid and .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 output

That 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 output

Use it as an MCP server

Claude Code:

claude mcp add utau-lyrics -- python -m utau_lyrics_mcp

Claude 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

create_song

Lyrics and chords in, .ust plus backing .mid and .wav out

lyrics_to_ust

The .ust only

render_backing

A backing track from chords alone

preview_syllables

Shows how each line will be split into notes

list_options

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+ or EN VCCV.

  • Japanese voicebank: write the lyrics in kana or use lyric_mode="romaji", with a JA phonemizer. A Japanese bank cannot sing English words.

  • The DiffSinger phonemizers 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-plugin

This 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.bat on 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_bar exists.

Tests

pip install -e ".[dev]"
pytest

Licence

MIT

Available Tools

5 tools
create_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

    B3.4/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      13
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to generate, inspect, and micro-tune OpenUtau .ustx project files and DiffSinger neural expression curves.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT