Bitwig Control Deck

Bitwig Control Deck is a local MCP bridge for Bitwig Studio. It gives any MCP client — Claude Code, Claude Desktop, Codex, or anything else that speaks MCP — exact, read-back-verified control of Bitwig tracks, devices, transport, native devices, and third-party plug-in parameters, plus a local status dashboard.

Everything runs on your machine and binds only to loopback addresses. Nothing is published or exposed to the network.

Bitwig Studio is a product of Bitwig GmbH. This project is an independent community tool and is not affiliated with or endorsed by Bitwig.

How it works

• A Bitwig controller extension (controller/ControlDeck.control.js, Controller API 18) listens on UDP port 50701 for an authenticated local request protocol.
• The MCP server (src/index.mjs) exposes Bitwig control as MCP tools and talks to the extension through a dependency-free local UDP client (src/bitwig-client.mjs).
• A per-install secret, generated by npm run setup and never committed, authenticates every request between the two.
• A native CoreMIDI helper (native/control_deck_midi_ports.c) publishes a virtual MIDI identity used only so Bitwig can auto-add the controller.
• A read-only status service (src/dashboard-server.mjs, port 50702) and a Next.js dashboard (dashboard/, port 50703) show bridge health, the current session, loaded devices, and a searchable local inventory of VST3, VST2, Audio Unit, and CLAP plug-ins.
• An optional native macOS wrapper (macos/) shows the dashboard in a WebKit window locked to the local address; external navigation is blocked.

Design rules

• Device loading uses Bitwig's Devices browsing session only. It never searches or loads presets.
• Track and device mutations require both the index and the exact current name.
• Device insertion is refused when an exact name has multiple matches, unless a Bitwig device-type filter disambiguates it.
• Third-party parameters use Bitwig's stable direct parameter IDs and are paged to keep messages small.
• Parameter writes report Bitwig's observed value after the change.

Tools

• Status and transport
• List, create, position, and rename Arranger cue markers with readback verification
• Build Arranger MIDI clips from existing launcher patterns at exact beat positions
• List, create, and safely delete tracks
• List and safely delete devices
• Search the Devices browser and insert one exact device
• Read the full direct parameter list for native and third-party devices
• Set a parameter by stable ID with readback
• Open a plug-in/device window

Requirements

• macOS 13 Ventura or newer (Apple silicon and Intel) — macOS is the only supported platform today. The core is platform-neutral and a Linux/Windows port is well-scoped; see PORTING.md.
• Bitwig Studio 6 (Controller API 18)
• Node.js 20+
• Xcode Command Line Tools (optional — only for the MIDI auto-detect helper and the wrapper app)

Full documentation — component descriptions, Bitwig setup, the complete MCP tool reference, troubleshooting, and uninstall — lives in HELP.md.

Install

Quickstart (no coding required)

1. Install Node.js — download the LTS version from nodejs.org and run its installer with the default options. (Control Deck runs on it; you never have to touch it again.)
2. Download Control Deck — use GitHub's green Code → Download ZIP button, unzip it, and move the folder somewhere permanent, like your home folder. Don't leave it in Downloads — the installer pins services to the folder's location and will ask you to move it.
3. Run the installer — right-click Install Control Deck.command and choose Open (macOS requires the right-click the first time for downloaded files). It installs everything, starts the background services, and opens the connection guide when it's done. It's safe to run again at any time.
4. Enable the controller in Bitwig — Settings → Controllers → confirm "Control Deck Bridge" is listed and enabled.
5. Connect your AI agent — the guide that opened (http://127.0.0.1:50703/connect) has copy-paste instructions for every client.

Developer setup

npm run setup is the same engine the installer uses — dependency install, native + dashboard builds, per-install secret, controller install, and launchd agents (written and activated). It's idempotent; re-run it after pulling changes or moving the checkout.

npm run setup

Flags for a tighter loop: --skip-build (no npm installs/builds), --skip-controller, --skip-agents. The granular pieces are still available as individual scripts (build:midi-ports, index:plugins, build:macos, and the dashboard's own dev/build/check).

What setup manages:

1. a per-install secret at data/bridge-token (shared by the controller and clients; never committed),
2. the controller script (secret stamped in) at ~/Documents/Bitwig Studio/Controller Scripts/Control Deck/,
3. three launchd agents pointing at this checkout: com.controldeck.midi-ports, com.controldeck.api, com.controldeck.dashboard.

Then add the MCP server to your client. For example, for Claude Code:

claude mcp add bitwig -- node /path/to/bitwig-control-deck/src/index.mjs

In Bitwig, open Settings → Controllers and confirm “Control Deck Bridge” is active.

Connecting other agents

The dashboard's Connect page (http://127.0.0.1:50703/connect) has copy-paste setup guides — rendered with your machine's real install path — for Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Grok CLI, fully local LLM harnesses (LM Studio, Ollama via mcphost), and any other MCP client, plus an honest discussion of what it would take (and cost, security-wise) to expose the bridge to remote connectors like claude.ai. The short version: any agent that can launch a stdio MCP server can drive Bitwig; remote cloud connectors are deliberately out of scope.

Control Deck dashboard

Open the deck at http://127.0.0.1:50703 (it starts at login if you activated the launch agents). It shows bridge health, the current Bitwig session, loaded devices, and a searchable local inventory of installed plug-ins. Its settings page controls bridge connection, refresh behavior, library defaults, density, color, and motion. Project changes continue to use the exact, read-back-verified MCP tools.

The optional native app is built with npm run build:macos as Bitwig Control Deck.app.

Local commands

npm run check          # syntax-check all sources
npm test               # bridge client tests
npm run index:plugins  # rebuild the local plug-in inventory
npm run build:macos    # build the native wrapper app

The dashboard has its own build check:

cd dashboard
npm run check

Security model

• The bridge listens on 127.0.0.1 UDP 50701 only; the status service and dashboard bind to loopback only.
• Every request must carry the per-install secret from data/bridge-token. The controller script refuses to start if the secret was never stamped.
• The wrapper app blocks all navigation away from the local dashboard address.

License

MIT