<p align="center"> <img src="Beat-Twin_logo.png" alt="Beat Twin logo" width="240"> </p>

Beat Twin

Beat Twin is a proof-of-concept bridge between Bitwig Studio and the Model Context Protocol (MCP).

It exposes a small local MCP server for agent-assisted music workflows while keeping DAW mutations behind explicit write-policy gates. The default mode is read-only.

What Works

• Read-only session inspection for transport, tracks, scenes, selected device, and remote controls.
• Plan-only arrangement suggestions based on the current read-only Bitwig snapshot.
• Transport, mixer, clip, scene, device, and application write tools, hidden and blocked by default.
• A Bitwig controller script that speaks JSON-RPC over a local TCP connection.
• Offline protocol and policy tests that run without launching Bitwig.
• A browser Playground for command-first song sketches, Tone.js audition, note editing, pattern tools, keyboard shortcuts, local undo/redo, JSON save/load, visible timeline feedback, a local command palette, and deterministic command drafts.

Architecture

MCP client
  -> Node.js MCP server (index.js)
  -> local TCP JSON-RPC bridge on 127.0.0.1:8888
  -> Bitwig controller script
  -> Bitwig Studio

The Node process is the MCP server. It connects to the Bitwig controller on demand through BITWIG_HOST and BITWIG_PORT.

The browser-first playground foundation now lives alongside the MCP bridge:

apps/playground
  -> @beat-twin/commands
  -> @beat-twin/core
  -> @beat-twin/audio-tone browser audition
  -> localStorage JSON save/load

The current Bitwig bridge still lives in index.js; adapter extraction is intentionally left for a later compatibility-focused slice. Browser audition is local Web Audio preview, not a Bitwig mutation or MCP write. Browser save/load is also local Playground state, not a Bitwig mutation. Browser pattern tools are local document edits for duplicate, quantize, and transpose. Browser undo/redo restores local Playground command snapshots only. Browser keyboard shortcuts invoke existing local Playground actions only. Browser timeline feedback is derived from local song state and does not call Bitwig. Browser command palette actions reuse the same local Playground action boundary. Browser command drafts parse known local phrases only; they are not an AI chat path.

Requirements

• Node.js 20 or newer
• pnpm 11.10.0 or newer
• Bitwig Studio for live/manual verification

Install

pnpm install

Run

node index.js

Configure your MCP client to run that command from this repository. A portable example lives in llm-mcp/mcp.example.json.

Codex example:

codex mcp add beat-twin --env BITWIG_HOST=127.0.0.1 --env BITWIG_PORT=8888 -- node /absolute/path/to/beat-twin/index.js

Install The Bitwig Controller

Copy the controller script into your Bitwig controller scripts directory.

Linux example:

mkdir -p "$HOME/Bitwig Studio/Controller Scripts/BeatTwin"
cp bitwig-controller/BeatTwin/BeatTwin.control.js "$HOME/Bitwig Studio/Controller Scripts/BeatTwin/BeatTwin.control.js"

macOS users commonly use:

$HOME/Documents/Bitwig Studio/Controller Scripts/

Windows users can copy bitwig-controller/BeatTwin into:

%USERPROFILE%\Documents\Bitwig Studio\Controller Scripts\

Then open Bitwig Studio and add the controller manually:

Beat Twin -> Beat Twin

If Bitwig was already open before installing the file, restart Bitwig or reload the controller settings before testing the bridge. See docs/LOCAL_MCP_SETUP.md for local verification commands and troubleshooting.

Safety Model

Beat Twin is read-only by default. At the MCP entry point, write tools are not listed by MCP clients and are blocked if called through the MCP server without an enabling policy.

This gate is enforced by the Node MCP server only. The Bitwig controller's TCP bridge (default 127.0.0.1:8888) is unauthenticated and executes any JSON-RPC command it receives. It does not apply the write policy. Anything able to reach that port can drive Bitwig regardless of the MCP write policy, so the MCP gate is not a barrier at the DAW itself. As a known limitation of this local proof of concept, treat the bridge as trusted-local-only: firewall the port and do not expose it on untrusted networks.

To enable a narrow write class:

BITWIG_MCP_WRITE_POLICY=transport node index.js

To enable multiple write classes:

BITWIG_MCP_WRITE_POLICY=transport,mixer_write node index.js

To enable every write class for disposable test sessions only:

BITWIG_MCP_ENABLE_WRITES=1 node index.js

Use write mode only in a disposable Bitwig project or a copy of real work.

Tests

Run the offline checks:

pnpm test

Run a syntax check:

node --check index.js

Live tests require Bitwig Studio, the controller script, and explicit write permissions. They are intentionally separate from the default test suite.

Useful Docs

• docs/BT-101-SESSION-INSPECTOR.md
• docs/BT-102-PROTOCOL-SMOKE.md
• docs/BT-103-POLICY-GATE.md
• docs/BT-104-ARRANGEMENT-PLAN.md
• docs/BITWIG_MANUAL_SMOKE_CHECKLIST.md
• docs/FUTURE-DIRECTION.md
• docs/PLAYGROUND_ARCHITECTURE.md
• docs/SPRINT-2-BROWSER-AUDITION.md
• docs/SPRINT-3-NOTE-EDITOR.md
• docs/SPRINT-4-SAVE-LOAD.md
• docs/SPRINT-5-PATTERN-TOOLS.md
• docs/SPRINT-6-UNDO-REDO.md
• docs/SPRINT-7-KEYBOARD-SHORTCUTS.md
• docs/AGENT_SETUP.md
• docs/LOCAL_MCP_SETUP.md

Status

Beat Twin is an experimental local integration, not a hardened production tool. It is published as an open-source foundation for safe, inspectable DAW control experiments.

License

MIT