mcp-svstudio
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 build2. 将 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 中启动服务器处理器
启动 Synthesizer V Studio 2 Pro。
打开或创建一个包含歌声轨道的项目。
在顶部菜单栏中,选择: Scripts > MCP > Start MCP Server Request Handler
后台处理器现已运行并保持响应。(要停止它,请选择 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 |
| 返回连接状态、脚本心跳时间戳和当前项目信息。 |
| 获取项目文件名、时长(以 blicks 为单位)、轨道数量、组数量、速度与拍号标记。 |
| 列出轨道及其名称、组引用计数、显示颜色和混音器设置(增益、声像、静音、独奏)。 |
| 列出项目库中的所有音符组及其 UUID 和音符数量。 |
| 获取指定轨道和组(基于 0 的索引)的音符,包括音高、起始时间、时长、歌词、音素和音符属性。 |
| 搜索匹配起始时间范围、音高范围、歌词子串/正则表达式或音素的音符。 |
| 向组中添加一个或多个音符。支持 |
| 按索引或定位器( |
| 按索引或定位器删除音符。支持 |
| 获取指定音符的用户自定义音素。 |
| 直接设置正式的以空格分隔的音素字符串( |
| 查询内部文本到音素引擎的结果和计算属性( |
| 获取音符属性(detune、languageOverride、phonesetOverride、musicalType、rapAccent、每个音素的时序/强度)。 |
| 修改音符属性和每个音素的属性( |
| 获取 |
| 修改轨道/组的歌声参数和歌声模式。 |
| 读取参数的自动化曲线点( |
| 添加、替换或移除自动化点,并带有范围验证。 |
| 启动播放走带。 |
| 暂停播放而不重置播放头。 |
| 停止播放并将播放头重置到起始位置。 |
| 将播放头移动到指定秒数位置。 |
| 读取播放头位置和状态( |
| 设置 |
| 在单个撤销事务中原子地执行多个操作,并带有预验证和差异预览。 |
音素操作与德语多音节歌词修复
问题
当从 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" }
]
}往返发音验证
调用
set_phonemes应用目标音素。调用
get_computed_phonemes重新查询 Synthesizer V 的内部合成器引擎。将计算出的音素与预期发音进行比较,以验证完全匹配。
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安全性、试运行与回滚保证
dry_run: true: 所有修改工具都支持dry_run: true。服务器返回预测的更改和差异,而不修改项目状态。应用内一步撤销(
project.newUndoRecord()): 每个修改性的 MCP 操作都会注册一个项目撤销记录。用户可以在 Synthesizer V Studio 中按Cmd+Z/Ctrl+Z立即还原整个操作。批处理中的事务回滚: 如果在
batch_edit期间发生错误,脚本会捕获修改前的状态,并在返回错误之前自动回滚已修改的项目。边界与范围验证:
MIDI 音高:
0-127响度:
-48dB 到+12dB张力 / 气声 / 性别:
-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)/AutomationPlaybackControl(play,pause,stop,seek,loop,getPlayhead)Project.newUndoRecord()
许可证
MIT License.
Available Tools
26 toolsadd_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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Read and edit DAW projects as an agent, save native Logic projects, convert projects between DAWs
Generate full songs with vocals, instrumentals and sound effects from text. One server for Suno, Google Lyria, Mureka, MiniMax, ACE-Step, YuE and ElevenLabs. Your agent can quote the credit cost before generating, start a song, wait for it to finish and return download links. Sign in with OAuth; optional daily credit caps; retries never charge twice.
Score video, make music as an agent: 100+ AI instruments play your MIDI, audio, stems, Logic/Ableton
Manage ElevenLabs voice agents and generate speech, music, sound effects, images, and video.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for Synthesizer V AI Vocal Studio, which allows LLMs to create/edit vocal tracks e.g. adding lyrics to the melody.616Apache 2.0
- FlicenseNot gradedqualityDmaintenanceControls OpenUtau (vocal synthesis software) from Claude Desktop, enabling project creation, editing, and live note manipulation via a bridge plugin.4-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to generate, inspect, and micro-tune OpenUtau .ustx project files and DiffSinger neural expression curves.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT