VOCALOID6 MCP

日本語版 README はこちら

Lets Claude (Claude Desktop / Claude Code) operate the VOCALOID6 Editor on Windows and write projects for VOCALOID3, 4, 5 and 6: melodies and lyrics in English, Japanese, Chinese, Korean and Spanish, any installed voicebank (VOCALOID:AI banks and classic VOCALOID3/4/5 banks), pitch and expression curves, playback and WAV/MIDI export.

How it works (and why there is no plugin)

VOCALOID6 has no plugin system, and its licence forbids reverse engineering it, so nothing here touches its code:

• The .vpr format was learned from projects VOCALOID6 itself saved; .vsqx follows vsq3.xsd / vsq4.xsd from the editor folder.

• The live tools click VOCALOID6's menus and dialogs through Windows UI Automation, the same interface screen readers use. They never send keystrokes, so they cannot type into another window.

• A live edit saves the project in VOCALOID6 (keeping anything you changed by hand), edits the .vpr, then reloads it with File > Revert. Each call is one step of this server's own undo / redo (VOCALOID6's undo history restarts after a reload). Expect a few seconds per live edit.

• Pronunciation is VOCALOID6's own: new notes carry a placeholder phoneme and VOCALOID6 works out the real one from the lyric when it loads the project. Pass phoneme only to override it (the note is then protected).

Every selector the live tools use lives in one table (SELECTORS in src/vocaloid6_mcp/ui.py); self_check reports which still match after a VOCALOID6 update. The project tools do not depend on the UI at all.

Related MCP server: GreanTeaDawy MCP Server

Requirements

• Windows with VOCALOID6 Editor (tested with 6.13; default install C:\Program Files\VOCALOID6\Editor)

• Python 3.11+ and uv (or pip)

• Voicebanks: VOCALOID6 AI banks and VOCALOID3/4/5 banks that VOCALOID6 can load. VOCALOID2 is not supported.

Install

git clone <this repo> vocaloid6-mcp
cd vocaloid6-mcp
uv venv -p 3.11
uv pip install -e ".[kanji]"

The kanji extra installs pykakasi, which turns Japanese kanji lyrics into hiragana.

Register with Claude

Claude Code

claude mcp add vocaloid6 -- "C:\path\to\vocaloid6-mcp\.venv\Scripts\vocaloid6-mcp.exe"

Claude Desktop: edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "vocaloid6": {
      "command": "C:\\path\\to\\vocaloid6-mcp\\.venv\\Scripts\\vocaloid6-mcp.exe"
    }
  }
}

Optional environment variable: VOCALOID6_EXE (path to VOCALOID6.exe). Optionally copy the skill folder into your Claude skills folder (e.g. .claude/skills/vocaloid6/). Its scripts/ are the song tools the skill uses for songs over a backing track: analyze_backing.py (tempo, beat 1, key, chords per bar, chord loop), check8.py (8-bar click + scale check), assemble.py and mix.py (stem placement and vocal mix). They are not part of the server and need their own Python with librosa and soundfile, plus ffmpeg on PATH:

python -m venv %LOCALAPPDATA%\song-analysisenv
%LOCALAPPDATA%\song-analysisenv\Scripts\pip install librosa soundfile

Usage

Ask Claude things like:

• "Is VOCALOID6 ready?" → vocaloid_status

• "Make a new song with an AI voicebank at 128 BPM and sing さくら さくら on A4 A4 B4."

• "Add a track for my English voicebank and sing 'hel-lo world' as quarter notes from C4."

• "Export a WAV to my desktop."

Basics: 480 ticks = one quarter note; pitch C4 = 60; part positions are absolute, note positions are relative to their part; track, part and note numbers count from 0.

Lyrics

English pitfalls VOCALOID6 shows: a word of several syllables on one note (hello) sings as u:, so hyphenate it (the tools warn); a - hold note outside Japanese also sings u:, so give the hold note the vowel as its phoneme.

Voicebanks and eras

list_voicebanks reads the registry (HKLM\SOFTWARE\VOCALOID3..6). AI banks report their languages; for classic banks the language is guessed from the bank name (language_source: "name").

Tool groups

• App: vocaloid_status, launch_vocaloid, close_vocaloid, self_check

• Project: new_project, open_project, save_project, reload_project, get_project, undo, redo

• Tempo: set_tempo, remove_tempo, set_time_signature

• Voicebanks: list_voicebanks, get_voicebank, list_styles

• Tracks / parts: add_track, edit_track, remove_track, add_part, edit_part, remove_part, fit_part

• Notes / lyrics: list_notes, add_notes, edit_notes, delete_notes, assign_lyrics, add_melody (e.g. A4:1 A4:1 B4:2 r:1)

• Curves: set_curve, get_curve, clear_curve (dynamics, pitchBend, pitchBendSens, breathiness, brightness, clearness, portamento, growl, xSynth, character, air, exciter)

• Playback / export: play, stop, export_wav (tracks=[...] renders stems: only those tracks, mute/solo restored afterwards), export_midi, import_midi, export_vsqx

• Utilities: note_to_midi, midi_to_note, beats_to_ticks, ticks_to_beats, split_lyrics

Safety

• open_project, new_project(open_in_vocaloid=true) and close_vocaloid refuse to discard unsaved changes in VOCALOID6 unless force=true.

• Live edits save the open project first, then snapshot the file (last 50 per project, in %LOCALAPPDATA%\vocaloid6-mcp\history) so undo can restore it.

• .vpr files are written atomically, and every zip entry and field the server does not know is kept.

Tests

uv pip install -e ".[kanji,test]"
.venv\Scripts\python tests\e2e_test.py          # file, voicebank, VSQX and utility tools over stdio
.venv\Scripts\python tests\e2e_test.py --live   # also drives the running VOCALOID6 (needs a voicebank)

The live test opens its own temporary project with force=false, so it stops if VOCALOID6 has unsaved changes. With lxml installed the VSQX output is validated against Yamaha's vsq3.xsd / vsq4.xsd.

Limits

• Live tools bring VOCALOID6's window to the front while they open its menus. Keys you type at that moment go to VOCALOID6 (a shortcut can open a dialog that blocks the next step: a leftover Open/Save dialog or its "File not found" box is closed automatically, other dialogs are reported). Leave the keyboard alone while a live tool runs, and especially during tests/e2e_test.py --live.

• Live tools need VOCALOID6's window (not minimised to a dialog-blocked state); a VOCALOID6 update can move menus (run self_check). The .vpr tools keep working regardless.

• Only VOCALOID6 6.13 with VOCALOID4 and VOCALOID6 AI banks was tested. VOCALOID3 and VOCALOID5 banks are found by the same registry scan but were not available to test.

• VOCALOID6 ignores the VSQX pre-measure, so a .vsqx it opens starts one bar later than in VOCALOID3/4.

• Style presets can be listed but are applied in VOCALOID6 itself.

License

MIT, see LICENSE. Not affiliated with Yamaha. VOCALOID is a trademark of Yamaha Corporation.