Skip to main content
Glama

Synthesizer V Studio 2 MCP Server (mcp-svstudio)

一个面向 Dreamtonics Synthesizer V Studio 2 Pro 的生产级 Model Context Protocol (MCP) 服务器,使生成式 AI 和 LLM 代理能够通过官方 Dreamtonics 脚本 API 安全、结构化且高效地操作音符、歌词、音素、歌声属性、参数和播放走带。


架构概述

Synthesizer V Studio 2 Pro 在嵌入式 Lua 5.4 / Duktape JS 环境中执行脚本,且没有外部网络套接字。为了实现高性能、低延迟和零 C 库依赖,此 MCP 服务器使用了一种原子文件邮箱 IPC 协议:

+--------------------------------------+
|       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 协议亮点

  • 原子文件重命名:写入 <id>.tmp 并原子重命名为 <id>.req / <id>.res,以防止竞态条件和部分文件读取。

  • 唯一请求 ID:即使在快速连续命令期间也能保证请求-响应配对。

  • 即时心跳活性检测:Lua 脚本每 500ms 更新一次 heartbeat.json。MCP 服务器检查心跳的新鲜度,并立即报告离线状态(<50ms),而不是因超时而挂起。

  • 自动垃圾回收:在启动时和轮询期间自动清理超过 60 秒的过期临时文件。


Related MCP server: utauMCP

安装与设置

前提条件

  • Node.js(v18 或更高版本;已在 v22 和 v26 上测试)

  • Synthesizer V Studio Pro(2.0 或 2.1+ 版本)

1. 构建 MCP 服务器

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

2. 将 Lua 脚本安装到 Synthesizer V Studio

运行自动安装程序:

npm run install-scripts

或者手动将 sv-scripts/ 中的文件复制到你的 Synthesizer V Studio 脚本文件夹:

  • 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. 在 Synthesizer V Studio 中启动服务器处理器

  1. 启动 Synthesizer V Studio 2 Pro。

  2. 打开或创建一个包含歌声轨道的项目。

  3. 在顶部菜单栏中,选择: Scripts > MCP > Start MCP Server Request Handler

  4. 后台处理器现已运行并保持响应。(要停止它,请选择 Scripts > MCP > Stop MCP Server Request Handler)。


MCP 客户端配置

Antigravity(~/.gemini/config/mcp_config.json 或项目配置)

{
  "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 Name

Description

get_server_status

返回连接状态、脚本心跳时间戳和当前项目信息。

get_project_info

获取项目文件名、时长(以 blicks 为单位)、轨道数量、组数量、速度与拍号标记。

list_tracks

列出轨道及其名称、组引用计数、显示颜色和混音器设置(增益、声像、静音、独奏)。

list_groups

列出项目库中的所有音符组及其 UUID 和音符数量。

get_notes

获取指定轨道和组(基于 0 的索引)的音符,包括音高、起始时间、时长、歌词、音素和音符属性。

find_notes

搜索匹配起始时间范围、音高范围、歌词子串/正则表达式或音素的音符。

add_notes

向组中添加一个或多个音符。支持 dry_run: true。

update_notes

按索引或定位器({ onset, pitch })更新现有音符。支持 dry_run: true。

delete_notes

按索引或定位器删除音符。支持 dry_run: true。

get_phonemes

获取指定音符的用户自定义音素。

set_phonemes

直接设置正式的以空格分隔的音素字符串(Note.setPhonemes())。

get_computed_phonemes

查询内部文本到音素引擎的结果和计算属性(SV.getComputedAttributesForGroup)。

get_note_attributes

获取音符属性(detune、languageOverride、phonesetOverride、musicalType、rapAccent、每个音素的时序/强度)。

set_note_attributes

修改音符属性和每个音素的属性(phonemes: [{ leftOffset, position, activity, strength }])。

get_voice

获取 NoteGroupReference 上的歌声参数(响度、张力、气声、性别、音调偏移、歌声模式参数)。

set_voice

修改轨道/组的歌声参数和歌声模式。

get_parameters

读取参数的自动化曲线点(pitchDelta、loudness、tension、breathiness、voicing、gender、vocalMode_*)。

set_parameters

添加、替换或移除自动化点,并带有范围验证。

play

启动播放走带。

pause

暂停播放而不重置播放头。

stop

停止播放并将播放头重置到起始位置。

seek

将播放头移动到指定秒数位置。

get_playhead

读取播放头位置和状态("playing"、"looping"、"stopped")。

loop

设置 tBegin 和 tEnd 之间的循环播放区域(以秒为单位)。

batch_edit

在单个撤销事务中原子地执行多个操作,并带有预验证和差异预览。


音素操作与德语多音节歌词修复

问题

当从 MuseScore 将 MusicXML 导入 Synthesizer V Studio 时,带有 syllabic=begin/end 的跨音符拆分的德语多音节单词(例如 schö- 和 -ne)常常会与歌词中的原始音素文本合并:

  • 预期音符 1:.sh er

  • 预期音符 2:.n ax

  • 如果放入歌词中,SynthV 中的结果:.sh er.n ax(导致发音警告和音素错误)。

解决方案:通过 MCP 直接注入音素

使用此 MCP 服务器,LLM 通过官方 API 直接设置歌词和音素:

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

往返发音验证

  1. 调用 set_phonemes 应用目标音素。

  2. 调用 get_computed_phonemes 重新查询 Synthesizer V 的内部合成器引擎。

  3. 将计算出的音素与预期发音进行比较,以验证完全匹配。


MuseScore MCP 集成流水线

[ 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

安全性、试运行与回滚保证

  1. dry_run: true: 所有修改工具都支持 dry_run: true。服务器返回预测的更改和差异,而不修改项目状态。

  2. 应用内一步撤销(project.newUndoRecord()): 每个修改性的 MCP 操作都会注册一个项目撤销记录。用户可以在 Synthesizer V Studio 中按 Cmd+Z / Ctrl+Z 立即还原整个操作。

  3. 批处理中的事务回滚: 如果在 batch_edit 期间发生错误,脚本会捕获修改前的状态,并在返回错误之前自动回滚已修改的项目。

  4. 边界与范围验证:

    • MIDI 音高:0 - 127

    • 响度:-48 dB 到 +12 dB

    • 张力 / 气声 / 性别:-1.0 到 +1.0

    • 发声:0.0 到 +1.0

    • 音高偏移:-1200 到 +1200 音分

    • 歌声模式:0 到 150


参考与官方 API 合规性

  • 官方脚本手册:https://resource.dreamtonics.com/scripting/index.html

  • 使用的主要官方 API:

    • 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()


许可证

MIT License.

Available Tools

26 tools
add_notesA

Add one or more notes to a track/group. Each note requires onset (in blicks, 1 quarter = 705,600,000 blicks), duration, pitch (MIDI 0-127), lyrics, and optional phonemes.

Inputs: notes (required), dry_run, groupIndex, trackIndex.

batch_editA

Execute multiple note/phoneme/voice/parameter operations in a single atomic transaction with snapshot rollback.

Inputs: operations (required), dry_run.

delete_notesB

Delete note(s) from a group by noteIndices or locator.

Inputs: dry_run, locator, noteIndex, groupIndex, +2 more.

find_notesA

Search notes by onset range, pitch range, lyrics substring/regex, or phonemes. Ideal for aligning with MuseScore score data.

Inputs: maxOnset, maxPitch, minOnset, minPitch, +4 more.

get_computed_phonemesB

Retrieve SynthV internal synthesis engine-computed phonemes and attributes (symbol, language, activity, position, accent) using SV.getComputedAttributesForGroup.

Inputs: groupIndex, trackIndex.

get_note_attributesB

Get detailed note attributes (detune, rapAccent, per-phoneme timing/activity: leftOffset, position, activity, strength).

Inputs: noteIndex (required), groupIndex, trackIndex.

get_notesA

Get all notes in a specific track and group reference (0-based indices). Returns pitch, onset, duration, lyrics, phonemes, and note attributes.

Inputs: groupIndex, trackIndex.

get_parametersA

Read automation curve points for a parameter (pitchDelta, vibratoEnv, loudness, tension, breathiness, voicing, gender, vocalMode_*).

Inputs: paramName (required), maxOnset, minOnset, groupIndex, +1 more.

get_phonemesA

Get user-specified phonemes for notes in a group or a specific noteIndex (returns empty string if none set).

Inputs: noteIndex, groupIndex, trackIndex.

get_playheadA

Get playhead position in seconds and status ('playing', 'looping', 'stopped').

Inputs: no named parameters.

get_project_infoA

Get current project metadata: duration, number of tracks, note groups, tempo marks, and measure marks.

Inputs: no named parameters.

get_server_logsB

Read the latest execution and error logs from Synthesizer V Studio Lua script.

Inputs: lines.

get_server_statusA

Check connection status with Synthesizer V Studio 2, script heartbeat, and current project info.

Inputs: no named parameters.

get_voiceC

Get voice settings on NoteGroupReference (paramLoudness, paramTension, paramBreathiness, paramGender, paramToneShift, vocalModeParams).

Inputs: groupIndex, trackIndex.

list_groupsA

List all note groups in the project library with group name, UUID, and note count.

Inputs: no named parameters.

list_tracksA

List all tracks in the project with track name, group references count, display color, and mixer settings (gain, pan, mute, solo).

Inputs: no named parameters.

loopB

Start loop playback between tBegin and tEnd in seconds.

Inputs: tEnd (required), tBegin (required).

pauseA

Pause playback in Synthesizer V Studio without resetting playhead.

Inputs: no named parameters.

playA

Start playback in Synthesizer V Studio.

Inputs: no named parameters.

seekB

Seek playhead to specific time in seconds.

Inputs: positionSeconds (required).

set_note_attributesC

Set note attributes and per-phoneme attributes (phonemes: [{ leftOffset, position, activity, strength }]).

Inputs: noteIndex (required), detune, dry_run, rapAccent, +5 more.

set_parametersB

Set automation points on parameter curve (add, replace_all, or remove_range).

Inputs: paramName (required), mode, points, dry_run, +5 more.

set_phonemesA

Directly assign formal SynthV space-separated phoneme strings to notes (e.g. '.sh er', '.n ax', 'g u: t'). Solves MusicXML lyric joining issues.

Inputs: assignments (required), dry_run, groupIndex, trackIndex.

set_voiceC

Set voice settings on NoteGroupReference (loudness, tension, breathiness, gender, toneShift, vocalModeParams).

Inputs: voice (required), dry_run, groupIndex, trackIndex.

stopA

Stop playback and return playhead to start position.

Inputs: no named parameters.

update_notesA

Update existing notes identified by 0-based noteIndex or locator (onset/pitch match). Supports dry_run.

Inputs: notes (required), dry_run, groupIndex, trackIndex.

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 26 tools

    Disambiguation4/5

    Tools are generally organized by resource (notes, phonemes, voice, parameters, transport) and the descriptions clarify distinctions such as get_phonemes vs get_computed_phonemes and get_voice vs get_parameters. Minor overlap remains between get_project_info/get_server_status and between note attribute and phoneme tools, but selection should be reliable.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (get_notes, set_voice, list_tracks, batch_edit), with list_ reserved for collections and get_/set_ for individual properties. The transport controls (play, pause, stop, seek, loop) are bare verbs and batch_edit is a compound, so the pattern is not perfectly uniform but remains predictable.

    Tool Count4/5

    26 tools is high but defensible for a Synthesizer V Studio integration that spans project status, note editing, phonemes, attributes, voice settings, automation curves, and transport. The count is at the upper edge of reasonable and every tool maps to a distinct operation rather than redundant duplicates.

    Completeness4/5

    The core note workflow is well covered: create/read/search/update/delete notes, phoneme handling, attribute editing, voice settings, parameter automation, and transport control. Missing group/track creation or rendering/export are notable gaps, but they appear outside the intended editing scope and can be worked around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Controls OpenUtau (vocal synthesis software) from Claude Desktop, enabling project creation, editing, and live note manipulation via a bridge plugin.
      4
      -
    • 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