Synthesizer V Studio 2 MCP Server (mcp-svstudio)

A production-grade Model Context Protocol (MCP) server for Dreamtonics Synthesizer V Studio 2 Pro, enabling Generative AI and LLM agents to safely, structurally, and effectively manipulate notes, lyrics, phonemes, vocal attributes, parameters, and playback transport via the official Dreamtonics Scripting API.

Architecture Overview

Synthesizer V Studio 2 Pro executes scripts within an embedded Lua 5.4 / Duktape JS environment without external network sockets. To achieve high performance, low latency, and zero C-library dependencies, this MCP server uses an Atomic File-Mailbox IPC Protocol:

+--------------------------------------+
|       LLM / MCP Client               |
|   (Antigravity / Claude / Cursor)    |
+------------------+-------------------+
                   | JSON-RPC over Stdio
                   v
+--------------------------------------+
|       Node.js MCP Server             |
|  - Tool Schema & Validation (Zod)    |
|  - Stable Note Locator Resolver      |
|  - Safe Diff & Dry Run Engine        |
|  - Mailbox IPC Client                |
+------------------+-------------------+
                   | Atomic Mailbox IPC (.req / .res)
                   | Live Heartbeat Monitor (heartbeat.json)
                   v
+--------------------------------------+
|  Synthesizer V Studio 2 Pro (Lua 5.4)|
|  `StartMCPServerRequestHandler.lua`  |
|  - Non-blocking SV:setTimeout loop   |
|  - Dreamtonics Official Scripting API|
|  - Automatic Snapshot Rollback & Undo|
+--------------------------------------+

IPC Protocol Highlights

• Atomic File Renames: Writes to <id>.tmp and atomically renames to <id>.req / <id>.res to prevent race conditions and partial file reads.

• Unique Request IDs: Guarantees request-response pairing even during rapid sequential commands.

• Instant Heartbeat Liveness: The Lua script updates heartbeat.json every 500ms. The MCP server checks heartbeat freshness and instantly reports offline state (<50ms) instead of hanging on timeouts.

• Automatic Garbage Collection: Auto-cleans stale temporary files older than 60 seconds on startup and during polling.

Related MCP server: aviutl2-mcp

Installation & Setup

Prerequisites

• Node.js (v18 or higher; tested on v22 & v26)

• Synthesizer V Studio Pro (Version 2.0 or 2.1+)

1. Build the MCP Server

git clone https://github.com/shotarokawade/SV-MCP.git
cd SV-MCP
npm install
npm run build

2. Install Lua Scripts to Synthesizer V Studio

Run the automated installer:

npm run install-scripts

Or manually copy the files in sv-scripts/ to your Synthesizer V Studio scripts folder:

• macOS: ~/Library/Application Support/Dreamtonics/Synthesizer V Studio 2/scripts/MCP/

• Windows: %APPDATA%\Dreamtonics\Synthesizer V Studio 2\scripts\MCP\

• Linux: ~/.local/share/Dreamtonics/Synthesizer V Studio 2/scripts/MCP/

3. Start the Server Handler in Synthesizer V Studio

1. Launch Synthesizer V Studio 2 Pro.

2. Open or create a project with vocal tracks.

3. In the top menu bar, select: Scripts > MCP > Start MCP Server Request Handler

4. The background handler is now running and responsive. (To stop it, select Scripts > MCP > Stop MCP Server Request Handler).

MCP Client Configuration

Antigravity (~/.gemini/config/mcp_config.json or project configuration)

{
  "mcpServers": {
    "synthv": {
      "command": "node",
      "args": ["/absolute/path/to/SV-MCP/build/index.js"],
      "env": {
        "MCP_SVSTUDIO_IPC_DIR": "/absolute/path/to/.mcp-svstudio/ipc"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "synthv": {
      "command": "node",
      "args": ["/path/to/SV-MCP/build/index.js"]
    }
  }
}

MCP Tool Reference

Phoneme Manipulation & German Multi-syllabic Lyrics Fix

The Problem

When importing MusicXML from MuseScore into Synthesizer V Studio, German multi-syllabic words split across notes (e.g. schö- and -ne) with syllabic=begin/end often get merged with raw phoneme text in lyrics:

• Intended Note 1: .sh er

• Intended Note 2: .n ax

• Result in SynthV if placed in lyrics: .sh er.n ax (causing pronunciation warnings and phonetic errors).

The Solution: Direct Phoneme Injection via MCP

Using this MCP server, the LLM sets lyrics and phonemes directly via official APIs:

{
  "trackIndex": 0,
  "groupIndex": 0,
  "assignments": [
    { "noteIndex": 0, "phonemes": ".sh er" },
    { "noteIndex": 1, "phonemes": ".n ax" }
  ]
}

Round-Trip Pronunciation Verification

1. Call set_phonemes to apply the target phonemes.

2. Call get_computed_phonemes to re-query Synthesizer V's internal synthesizer engine.

3. Compare the computed phonemes against expected pronunciation to verify exact match.

MuseScore MCP Integration Pipeline

[ MuseScore MCP ]
       │ 1. Extract note pitches, onset blicks, measure positions, and lyric syllables
       ▼
[ LLM Agent ]
       │ 2. Perform German grapheme-to-phoneme (G2P) conversion to Synthesizer V phonemes
       │    (e.g., "Freude" -> [".f r oy", "d ax"])
       ▼
[ Synthesizer V MCP ]
       │ 3. `find_notes` or `get_notes` matching onset and measure range
       │ 4. `batch_edit` with `dry_run: true` to inspect diff
       │ 5. `batch_edit` with `dry_run: false` to apply notes and `set_phonemes`
       │ 6. `get_computed_phonemes` to verify synthesis pronunciation

Safety, Dry Run, and Rollback Guarantees

1. dry_run: true: All mutation tools support dry_run: true. The server returns the predicted changes and diff without modifying project state.

2. One-Step In-App Undo (project.newUndoRecord()): Every mutating MCP operation registers a project undo record. The user can press Cmd+Z / Ctrl+Z inside Synthesizer V Studio to instantly revert the entire operation.

3. Transaction Rollback in Batch: If an error occurs during batch_edit, the script captures the pre-mutation state and automatically rolls back modified items before returning the error.

4. Boundary & Range Validation:

   • MIDI pitch: 0 - 127

   • Loudness: -48 dB to +12 dB

   • Tension / Breathiness / Gender: -1.0 to +1.0

   • Voicing: 0.0 to +1.0

   • Pitch Delta: -1200 to +1200 cents

   • Vocal Mode: 0 to 150

References & Official API Compliance

• Official Scripting Manual: https://resource.dreamtonics.com/scripting/index.html

• Key Official APIs Used:

  • Note.getPhonemes() / Note.setPhonemes(phonemes)

  • SV.getPhonemesForGroup(groupRef)

  • SV.getComputedAttributesForGroup(groupRef) (SynthV 2.1.1+)

  • Note.getAttributes() / Note.setAttributes(attributes)

  • NoteGroupReference.getVoice() / NoteGroupReference.setVoice(voice)

  • NoteGroup.getParameter(name) / Automation

  • PlaybackControl (play, pause, stop, seek, loop, getPlayhead)

  • Project.newUndoRecord()

License

MIT License.