Vcv Rack Plugin MCP Server

vcv机架mcp服务器

vcv-rack-mcp-server 允许AI客户端通过一个专用的Rack模块控制实时VCV Rack 2补丁，该模块同时暴露HTTP和MCP端点。上面的屏幕截图显示了 MCP Server 模块与通过服务器创建并保存回Rack的简单环境无人机补丁一起运行。

通过一个模块将AI客户端连接到VCV机架2，该模块通过HTTP和MCP公开机架。 随着 MCP Server 模块加载到补丁中，MCP客户端可以检查补丁、添加模块、连接电缆、设置参数以及保存或加载 .vcv 文件夹。

这个插件做什么

该插件添加了一个VCV机架模块：

• MCP Server (RackMcpServer)

启用该模块后，它将在上启动本地服务器 127.0.0.1 使用配置的端口（默认 2600)并暴露：

• POST /mcp 用于MCP JSON-RPC请求
• GET /status 以及用于脚本和调试的其他REST端点

典型用途：

• 从Claude Desktop、Cursor或其他MCP客户端控制机架补丁
• 从终端构建脚本补丁
• 在以编程方式创建补丁之前，检查已安装的插件和模块块
• 从自动化工具中保存和加载补丁

运作原理

Claude Desktop / Cursor / any MCP client
        |
        | JSON-RPC 2.0  (POST http://127.0.0.1:2600/mcp)
        v
  MCP Server module inside VCV Rack
        |
        | Rack engine API
        v
  Current patch: modules, cables, params, save/load

服务器仅在以下情况下工作：

• VCV机架打开
• 这 MCP Server 模块存在于补丁中
• 模块已打开

安装

来自VCV库

一旦插件在VCV库中获得批准：

1. 打开VCV机架2。
2. 登录您的VCV帐户。
3. 打开图书馆并订阅 MCP Server 通过 Neural Harmonics.
4. 必要时重新启动机架。
5. 从浏览器中添加模块 Utility.

来自GitHub发布

1. 打开 页面。
2. 下载 .zip 为您的平台创建文件。
3. 解压缩它。您应该得到一个名为的文件夹 VCVRackMcpServer.
4. 将该文件夹移动到Rack 2插件文件夹中：

macOS Apple Silicon: ~/Library/Application Support/Rack2/plugins-mac-arm64/
macOS Intel: ~/Library/Application Support/Rack2/plugins-mac-x64/
Linux x64: ~/.local/share/Rack2/plugins-lin-x64/

1. 重新启动Rack并从浏览器添加模块。

构建自己的发布包

如果你是从源代码构建的，并希望在GitHub Release上使用相同的可安装工件：

make dist

这创建了一个 .zip 存档在 dist/例如：

dist/VCVRackMcpServer-2.1.0-mac-arm64.zip

解压缩该文件并移动提取的 VCVRackMcpServer 将文件夹放入Rack插件目录。

在Rack中快速启动

1. 打开VCV机架2。
2. 创建或打开补丁。
3. 添加 MCP Server 模块。
4. 离开港口 2600 除非你需要一个不同的端口。
5. 切换 ON/OFF 直到状态LED变为绿色。
6. 在客户端连接时保持此补丁打开。

服务器现在将在以下位置进行监听：

http://127.0.0.1:2600

第一次补丁演练

如果你想快速进行烟雾测试，请构建这个最小的补丁：

Fundamental VCO -> Core AudioInterface2

1. 启动VCV机架并添加 MCP Server.
2. 打开模块，确认LED为绿色。
3. 添加一个 Core AudioInterface2 机架中的模块，这样音频就有了用武之地。
4. 如果您还没有在机架中手动配置音频驱动程序和输出设备，请在机架中进行配置。
5. 使用以下命令之一添加 Fundamental VCO.
6. 将VCO输出连接到上的左右输入 AudioInterface2.
7. 测试前降低系统音量，然后根据口味调整振荡器频率。

使用附带的CLI帮助程序，流程如下：

python3 skills/vcvrack_client.py status
python3 skills/vcvrack_client.py library Fundamental
python3 skills/vcvrack_client.py library Core
python3 skills/vcvrack_client.py add Fundamental VCO
python3 skills/vcvrack_client.py add Core AudioInterface2
python3 skills/vcvrack_client.py modules
python3 skills/vcvrack_client.py connect  0  0
python3 skills/vcvrack_client.py connect  0  1

如何使用此插件

可靠的工作流程是：

Start Rack -> add MCP Server -> turn it on -> verify /status -> connect your AI client -> search library -> add modules -> inspect module IDs and params -> connect cables

对于人工智能驱动的补丁构建，有两条实用规则非常重要：

• Rack编辑在Rack的UI线程上执行。如果Rack正忙、隐藏在模态后面或无法正常行走，即使请求有效，MCP调用也可能超时。
• 参数值通常是原始旋钮位置，而不是音乐单位。在尝试直接设置“65 Hz”、“200 ms”、“saw”或类似概念之前，始终检查模块的参数元数据。

1.验证服务器是否处于活动状态

从终端：

curl -s http://127.0.0.1:2600/status | python3 -m json.tool

您应该得到一个包含采样率和模块计数的JSON响应。

2.构建前发现可用模块

询问服务器安装了哪些插件和模块：

curl -s "http://127.0.0.1:2600/library?q=oscillator" | python3 -m json.tool
curl -s "http://127.0.0.1:2600/library/Fundamental" | python3 -m json.tool

这很重要，因为VCV机架自动化取决于确切的插件和模块块。

3.添加模块并检查

示例：添加VCO并检查其详细信息。

curl -s -X POST http://127.0.0.1:2600/modules/add \
  -H "Content-Type: application/json" \
  -d '{"plugin":"Fundamental","slug":"VCO"}' | python3 -m json.tool

curl -s http://127.0.0.1:2600/modules | python3 -m json.tool
curl -s http://127.0.0.1:2600/modules/1 | python3 -m json.tool

在布线电缆或设置参数时使用返回的模块ID。

4.连接电缆并调整参数

请求示例：

curl -s -X POST http://127.0.0.1:2600/cables \
  -H "Content-Type: application/json" \
  -d '{"outputModuleId":1,"outputId":0,"inputModuleId":2,"inputId":0}' | python3 -m json.tool

curl -s -X POST http://127.0.0.1:2600/modules/1/params \
  -H "Content-Type: application/json" \
  -d '{"params":[{"id":0,"value":0.0}]}' | python3 -m json.tool

参数自动化的重要注意事项：

• 呼叫 GET /modules/:id/params 首先使用返回的 name, min, max, value, displayValue，可选 options 田野是真理的源泉。
• 不要假设参数 0 表示频率（单位为Hz）或类似的值 65 意味着65Hz。许多模块公开了标准化或模块特定的控制范围。
• 喜欢小 POST /modules/:id/params 批处理，然后再次读取参数以确认更改，然后再继续。
• 如果写入超时，首先确认Rack有响应 MCP Server 模块仍处于启用状态，然后以较小的步骤重试。

与MCP客户端一起使用

克劳德桌面版

将此添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上，或您平台上的等效配置路径：

{
  "mcpServers": {
    "vcvrack": {
      "type": "http",
      "url": "http://127.0.0.1:2600/mcp"
    }
  }
}

然后：

1. 重新启动克劳德桌面
2. 打开VCV机架 MCP Server 模块已启用
3. 让克劳德检查或构建补丁

示例提示：

• List the modules currently in my Rack patch.
• Search the installed Rack library for oscillators and add a good starting VCO.
• Build a simple subtractive synth with VCO, VCF, VCA, ADSR, and Audio.
• Build a simple ambient drone. Inspect each module's params before setting them, and treat displayed param values as authoritative instead of guessing in Hz.

MCP超时故障排除

如果MCP工具如 vcvrack_set_params 报告超时：

1. 确保VCV机架仍然打开，补丁处于活动状态，并且 MCP Server 模块LED为绿色。
2. 检查机架是否响应，并且没有被对话框、浏览器搜索字段、菜单或文件选择器阻止。
3. 按以下顺序重试工作流： vcvrack_get_status -> vcvrack_get_module -> vcvrack_get_params -> vcvrack_set_params.
4. 一次写入一个或两个参数，并将值保存在报告中 min 和 max 范围。
5. 每次写入后重新读取参数，而不是假设模型正确猜测了控制映射。

游标或其他MCP客户端

使用相同的服务器URL:

{
  "servers": {
    "vcvrack": {
      "type": "http",
      "url": "http://127.0.0.1:2600/mcp"
    }
  }
}

与附带的CLI帮助程序一起使用

此回购包括 skills/vcvrack_client.py，一个用于与本地Rack服务器通信的小型Python CLI。

检查连接：

python3 skills/vcvrack_client.py status

命令格式：

python3 skills/vcvrack_client.py [--port PORT]  [args...]

常用命令：

现成的演练现场直播 skills/examples/.

REST API参考

所有回复都使用以下信封之一：

{ "status": "ok", "data": ... }

{ "status": "error", "message": "..." }

从源头构建

先决条件

• CMake 3.21+或GNU Make
• C++17编译器
• curl 或 wget 如果你使用 Makefile 路径
• jq 和 zip 为了 make dist

用Make构建

make
make install
make dist

如果您已有Rack SDK，请使用现有的Rack SDK：

make RACK_DIR=/path/to/Rack-SDK

使用CMake构建

cmake -B build
cmake --build build --parallel
cmake --install build

释放

1. 更新 plugin.json 到新版本。
2. 承诺并推动。
3. 构建发布工件或让CI构建它们。
4. 为该版本创建GitHub版本。

如果你标记git中的releases，请保持标记与对齐 plugin.json例如：

git tag v2.1.0
git push origin v2.1.0

发布到VCV图书馆

对于开源插件，正常的路径是通过 VCVRack/library 存储库。

1. 在中打开问题 VCVRack/library.
2. 使用插件slug作为问题标题： VCVRackMcpServer.
3. 包含源存储库URL： https://github.com/Neural-Harmonics/vcv-rack-plugin-mcp-server.
4. 等待维护人员审查并添加插件。
5. 对于以后的更新，请对新版本的同一问题发表评论并提交SHA。

用于审批的元数据主要来自 plugin.json，因此保持其URL、版本和模块信息的最新状态。

注意事项和限制

• 该插件控制机架补丁，而不是机架应用程序设置。
• 音频驱动程序和设备选择仍然需要在机架中手动配置。
• 默认情况下，服务器仅在本地，并打算在同一台机器上使用。
• 确切的插件/模块块取决于机架库中安装的内容。

许可证

MIT。看 许可证.

该项目还使用 cpp httplib，这是麻省理工学院授权的。