Rack MCP

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.git

Demo

A 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:

$ claude  # with the rack-mcp server connected

→ list_rack_instances
  ← 1 instance   id 4089a9eb…  (patch: Untitled)
→ get_rack_status
  ← connected   Rack 2.6.6 Pro   bridge protocol v1
→ list_installed_models
  ← 53 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 7f6179b15430…

→ describe_patch
  ← Signal path into Audio 2: MIDI to CV → VCO → VCF → VCA → Audio 2
      also feeding it: ADSR EG → VCA, MIDI to CV → ADSR EG
→ 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:

Related MCP server: beat-twin

Components

The MCP surface is 29 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.

Documentation

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

• Normative specification

Security

• Threat model

• Pairing and multi-instance guide

• VCV licensing note

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

• Adapter authoring guide

• Recipe authoring guide

Status

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.

Development

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.mjs

Live 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() cleanly

New here? Start with the clean-machine install walkthrough.

Use it from Claude Code

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.js

The 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.

Unsupported environments

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.