svs-mcp

An MCP (Model Context Protocol) server for Synthesizer V Studio 2 Pro, focused on AI-driven input of lyrics and notes: compose melodies, flow lyrics onto them, and fine-tune pronunciation — all from an AI client such as Claude.

• macOS + SV Studio 2 Pro only. Local build only (not published to npm).
• Design notes and background live in docs/plan.md.

How it works

SV's scripting API has no network access, so a small Lua script runs inside SV Studio and exchanges JSON files with the MCP server:

AI client (Claude, etc.)
   │ MCP (stdio)
   ▼
svs-mcp server (Node.js)
   │ request.json / response.json in ~/.svs-mcp/bridge/
   ▼
SVSMCPBridge.lua (resident script inside SV Studio, polls every 100ms)

Requests carry unique IDs (stale responses are discarded) and all file writes are atomic (temp file + rename).

Setup

Requirements: Node.js 20+, Synthesizer V Studio 2 Pro on macOS.

npm install
npm run build
npm run install-sv   # copies the bridge scripts into SV's scripts folder

Then, in SV Studio:

1. Run Scripts > Rescan (or restart SV Studio).
2. Run Scripts > SVS MCP > "SVS MCP Bridge: Start". A dialog confirms the bridge is running; it keeps running in the background.

Finally, register the server with your MCP client:

{
  "mcpServers": {
    "svs-mcp": {
      "command": "node",
      "args": ["/path/to/svs-mcp/dist/index.js"]
    }
  }
}

To verify the setup without an MCP client, run npm run ping — it prints SV's host info when the bridge answers, or setup guidance when it doesn't (exit 1), which also makes the whole setup scriptable for an AI agent: only the two Scripts-menu clicks above need a human.

To stop the bridge, run "SVS MCP Bridge: Stop" from the Scripts menu. To remove everything, npm run uninstall-sv.

Tools

Tool	Purpose
ping	Check the bridge is alive; returns SV host info
get_project_info	Project overview: tempo, time signatures, tracks, groups, mixer state
get_notes	List notes (lyrics, pitch, position) of a track/group, filterable by measure
add_track	Add a track
create_group	Add a note group to a track
insert_notes	Insert notes: lyrics + pitch ("C4") + musical position (measure/beat) + note value ("1/8")
update_notes	Edit lyrics/pitch/timing of existing notes by index
delete_notes	Delete notes by index
set_lyrics	Flow lyrics (one syllable per note) onto an existing melody
get_phrases	Analyze a melody into phrases/sections with repetition (shape) labels
set_time_signature	Add/update/remove time signature marks (align SV's grid with the music)
open_lyrics_editor	Browser page for the user to adjust syllable boundaries before applying
get_lyrics_editor_result	Fetch the user-edited syllable plan from the editor
get_phonemes	Inspect the phonemes SV will actually sing
set_phonemes	Override phonemes per note ("k a"); empty string resets
set_language	Per-note language override for mixed-language lyrics

Positions and durations use musical notation (1-based measures/beats, note values like 1/8 or dotted 1/8.); the server converts to SV's internal blicks. Japanese lyrics take one kana per note; - extends the previous vowel.

For putting lyrics on an imported MIDI melody, see docs/lyrics-workflow.md.

Important: groups and singers

In SV Studio 2 the singer is attached per note group, and notes placed in a track's main group are not synthesized (they appear in the piano roll but stay silent). Therefore:

• insert_notes targets the first non-main group by default and auto-creates a group when the track has none.
• New tracks/groups inherit SV's default singer. There is no scripting API for singer selection, so if a group has no singer, pick one in the SV UI (select a note of the group, then use the Voice panel).

Troubleshooting

• Tool calls time out — the bridge is probably not running. Run "SVS MCP Bridge: Start" in SV Studio. Only one MCP server instance should talk to one SV instance.
• Notes appear but don't sound — check that the notes are in a non-main group (get_project_info shows the groups) and that the group has a singer assigned in the Voice panel. Also check track/group mute states, which get_project_info reports.
• Wrong pronunciation — inspect with get_phonemes, then correct with set_phonemes or set_language.

Development

npm test        # unit + protocol tests + e2e against the real Lua bridge (needs `lua` on PATH)
npm run build   # tsc

test/sv-stub.lua emulates the SV host so the actual bridge script can be tested without SV Studio. After changing sv-scripts/, re-run npm run install-sv and restart the bridge from SV's Scripts menu.

License

MIT. Bundles rxi/json.lua (MIT) inside the bridge script.