A production-quality, safety-first Model Context Protocol integration for VCV Rack 2.6.6 (Free or Pro, standalone GUI mode).
Rack MCP lets an MCP client (Claude and other MCP hosts) discover running Rack instances, inspect patches, explain and validate signal flow, preview and atomically apply structured patch changes, manage patch files with checkpoints and recovery, and read signal telemetry through a dedicated Probe module — all locally, over an authenticated loopback bridge, with explicit confirmation for destructive changes.
Repository: https://github.com/ColonelKernel/vcv-rack-mcp
git clone https://github.com/ColonelKernel/vcv-rack-mcp.gitA live session — building and validating a subtractive-synth voice through the
MCP against a running Rack instance. This is real tool output, captured by
pnpm --filter @rackmcp/integration run demo:
Transcript (text)
$ claude # with the rack-mcp server connected
→ list_rack_instances
← 1 instance id 369ce713… (patch: Untitled)
→ get_rack_status
← connected Rack 2.6.6 Pro bridge protocol v1
→ list_installed_models
← 55 models installed (Core, Fundamental, RackMCP)
→ resolve recipe "basic_mono_subtractive"
← resolved 6 roles → installed models, 0 unresolved
→ build_patch (19 operations)
← committed 19 ops applied fingerprint bfe2b02b1c65…
→ describe_patch
← Signal path into Audio 2: MIDI to CV → VCO → VCF → VCA → Audio 2
also feeding it: MIDI to CV → ADSR EG, ADSR EG → VCA
→ validate_patch
← valid ✓ 0 errors · 0 warnings · 0 info
# a subtractive voice, built and validated through MCP — safely, reversibly.
…and the patch those tool calls actually build, in the running Rack window —
MIDI→CV → VCO → VCF → VCA with an ADSR envelope → Audio, wired live over the
bridge. The MCP Bridge panel on the left shows the connection state
(op txn.commit, read-only, one client) that the session above produced:
| Path | What | License |
|---|---|---|
apps/mcp-server |
Stdio MCP server (TypeScript, MCP SDK 1.30.0) | MIT |
plugins/RackMCP |
Rack 2 plugin: Bridge, Probe, Tutorial and Chat modules, loopback bridge service (C++11) | GPL-3.0-or-later |
packages/schemas |
Canonical Zod schemas → JSON Schema + C++ codegen | MIT |
packages/protocol |
Bridge framing + client (TypeScript side) | MIT |
packages/adapters |
22 versioned module adapters (Core + Fundamental + RackMCP) | MIT |
packages/recipes |
8 versioned high-level patch recipes | MIT |
packages/test-client |
Scriptable MCP test client | MIT |
The MCP surface is 32 tools, 6 resources (rack://…), and 5 prompts.
See the licensing note for why the plugin is
GPL-3.0-or-later while the server and packages are MIT.
Architecture
- ADR-0001 — Execution model
- ADR-0002 — Bridge lifecycle and threading
- ADR-0003 — Canonical schema codegen
- ADR-0004 — Adapter and recipe knowledge model
- Threading and real-time-safety model
- Local bridge protocol
- Definition-of-done audit
- Contract census (generated)
- Normative specification
Security
Tools and operation
- MCP tool reference (generated)
- Installation guide
- Clean-machine install walkthrough
- Configuration examples for MCP hosts
- Backup and recovery
- Troubleshooting
- Compatibility matrix
- Release and rollback procedure
Extending
All eleven delivery phases are complete: schemas and test infrastructure; plugin lifecycle, manifest, authentication, and status; stdio server and discovery; read-only snapshot and catalog; parameter mutation; module and cable transactions; preview/confirm/rollback; patch files and recovery; Probe telemetry; adapters, recipes, validation, prompts, and resources; and security hardening, packaging, and documentation. See the definition-of-done audit for the spec-by-spec evidence.
Verified live on macOS arm64; Windows x64, Linux x64, and macOS x64 build and test in CI. See the compatibility matrix.
pnpm install
pnpm run build # build all TS packages + the server
pnpm run test # unit/contract tests across the workspace
pnpm run gen # regenerate JSON Schema + C++ protocol artifacts
pnpm run check:gen # fail if generated protocol artifacts are stale
pnpm run docs:tools # regenerate docs/tools/tool-reference.md from the schema
# C++ core tests (framing, queues, crypto, JSON limits, telemetry, service, secret/manifest files)
cmake -S tests/cpp -B tests/cpp-build && cmake --build tests/cpp-build && ctest --test-dir tests/cpp-build
# Build and package the Rack plugin
./scripts/fetch-rack-sdk.sh # pinned Rack SDK 2.6.6
make -C plugins/RackMCP RACK_DIR=../../vendor/Rack-SDK
make -C plugins/RackMCP dist RACK_DIR=../../vendor/Rack-SDK # -> dist/*.vcvplugin
# Bundle the server as a single reproducible file for a host to launch
pnpm --filter @rackmcp/mcp-server run bundle # -> dist/bundle/rack-mcp-server.mjsLive integration tests launch the installed VCV Rack 2 Pro 2.6.6 against an isolated user directory:
pnpm --filter @rackmcp/integration run write # transaction lifecycle
pnpm --filter @rackmcp/integration run recipes # adapters, recipes, resources
pnpm --filter @rackmcp/integration run probe # telemetry plumbing
pnpm --filter @rackmcp/integration run quit # graceful quit runs destroy() cleanlyNew here? Start with the clean-machine install walkthrough.
This repo ships a project-scoped .mcp.json that wires up the
rack-mcp server for Claude Code. After building the server, open the repo in
Claude Code and approve the server when prompted:
pnpm install && pnpm -r build # produces apps/mcp-server/dist/index.jsThe server points at your real Rack user directory, so start VCV Rack 2.6.6 with the RackMCP plugin (add a Bridge module) before using the tools. For other hosts (Claude Desktop, etc.), or to run the self-contained bundle, see the configuration examples and the installation guide.
Stated plainly: Rack Pro inside a DAW, headless Rack, and Rack versions other than 2.6.6 are not supported. Arbitrary signal monitoring is available only through the Probe module, and opaque third-party module state is never mutated without a matching adapter. See the compatibility matrix.