Documentation menu
On this page

This page covers the extension, the optional MCP server, upgrades, and the limits of activation checks. For a short first connection, see Quickstart. The release-bundle path below is independently usable without MCP; start MCP only after the direct read-only check succeeds.

Requirements

  • Bitwig Studio 6.1.1 for the version-gated native Grid graph runtime.
  • A local account that can write to the Bitwig Extensions directory.
  • Python 3.10 or newer for the read-only example client.
  • uv for the optional Python MCP environment only.
  • Java 21 or newer and Maven when building the extension from source.
  • ffmpeg and ffprobe for the optional audio-file tools (brew install ffmpeg on macOS).

For a release-bundle first connection, you do not need Java, Maven, uv, an MCP client, external hardware, or a MIDI port. The bridge uses loopback (127.0.0.1:8765) and does not claim MIDI ports. Controller API 25 is the public compile-time API; it is not a promise that private Grid bindings work on another Bitwig release. The private native runtime checks the exact supported Bitwig version and fails closed when its signatures do not match.

The source currently defines 57 MCP tools. That is a source registration catalog, not live acceptance: the running server's tools/list response and the native capabilities response are authoritative for a particular session. The current surface and its explicit absences are listed in the current tool reference.

Install a release bundle

Download the matching full bitwig-grid-bridge-VERSION.zip from GitHub Releases, or build from source. Replace VERSION with the release number you downloaded. A full bundle contains the extension, example client, Python package, documentation, and source metadata.

Extract the ZIP and open a terminal in the extracted bundle's top-level folder. The extension file must be at that top level. Use the disclosure for the platform you are running; each command is only a file copy and is not proof that Bitwig loaded the new code.

macOS
mkdir -p "$HOME/Documents/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension \
  "$HOME/Documents/Bitwig Studio/Extensions/BitwigGridBridge.bwextension"
Linux
mkdir -p "$HOME/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension "$HOME/Bitwig Studio/Extensions/"
Windows PowerShell

Run from the extracted bundle folder:

$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\BitwigGridBridge.bwextension (Join-Path $extensions 'BitwigGridBridge.bwextension')

A copied .bwextension is only a file operation. After copying, save work, fully restart Bitwig deliberately, then add or enable Bitwig Grid Bridge under Settings → Controllers. Keep one installed controller copy and one enabled bridge instance. A ControllerHost.restart or similar public restart can retain an already loaded class definition in the same macOS session, so it is not sufficient proof of replacement. Do not use a throwaway native attach probe as an activation test.

Build from source

This is the advanced alternative when a matching full release bundle is not available or when the current native runtime is required. Clone the repository and run the platform-specific path from its root. The direct read-only example client still needs only Python after the extension is installed.

macOS and Linux — Makefile build and install

With Java 21 or newer and Maven available:

git clone https://github.com/critx-jt/bitwig-grid-bridge.git
cd bitwig-grid-bridge
mvn -B -f extension/pom.xml package

With make available, the supported build-and-install path is:

make install-extension

The Makefile destination is ~/Documents/Bitwig Studio/Extensions on macOS and ~/Bitwig Studio/Extensions on Linux. Override it for a nonstandard location with an absolute path:

make install-extension BITWIG_EXTENSIONS_DIR="/absolute/path/to/Extensions"

The direct Linux equivalent, when you do not use make, is:

mkdir -p "$HOME/Bitwig Studio/Extensions"
cp extension/target/BitwigGridBridge.jar \
  "$HOME/Bitwig Studio/Extensions/BitwigGridBridge.bwextension"
Windows PowerShell — Maven build and copy

The Unix make install-extension target does not select a Windows directory. From a PowerShell checkout root, build with Maven and copy the resulting JAR as the .bwextension file:

git clone https://github.com/critx-jt/bitwig-grid-bridge.git
Set-Location bitwig-grid-bridge
mvn -B -f extension/pom.xml package
$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\extension\target\BitwigGridBridge.jar (Join-Path $extensions 'BitwigGridBridge.bwextension')

macOS build prerequisites

With Homebrew already installed:

brew install openjdk maven uv
export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"
java -version
mvn -version
make install-extension
uv sync --frozen

uv sync --frozen is only needed for the MCP server, not for the direct example client. The build enables deprecation warnings as errors because the JVM rejects the deprecated public SDK calls at runtime.

After installing from source, save work and restart Bitwig before enabling the controller. Do not repeatedly add controller instances while testing a replacement.

Check the running versions and capability gates

The following commands are read-only procedures. They are not a claim that a live Bitwig session has been verified by this repository revision. Start from the extracted bundle or checkout root, not from the Extensions directory.

On macOS or Linux:

python3 examples/automation/grid_bridge_demo.py inspect
python3 examples/automation/grid_bridge_demo.py graph

Use python instead if that is the Python 3 command on the machine. In Windows PowerShell:

py -3 examples\automation\grid_bridge_demo.py inspect
py -3 examples\automation\grid_bridge_demo.py graph

The inspect command prints capabilities, selected-device inspection, and selected-device state. For the exact success checklist (ok, protocol 4, identity fields, and the representative parameter fields), see What success looks like. A successful inspection should report the extension, host, and API identity and selected device state. The graph command is meaningful only for a supported selected Grid device; a non-Grid selection may legitimately report no graph.

For the native endpoint, confirm protocol 4 and inspect the capability flags, including the host version/platform and the grid_graph fields. In particular, do not perform graph writes unless the response supports the required flags (runtime_supported, graph_available, inspection/catalog, insertion/parameter/connection support, revision_guards, and display_value_resolution, as applicable). Public controls can remain usable when the private graph is unavailable.

With MCP enabled, call tools/list and begin with read-only calls such as get_grid_capabilities, get_selected_device_state, and grid_song_state. Do not infer capabilities from a copied file, a package version, or a historical module inventory. The historical decoded inventory in repository notes is evidence about an earlier capture, not current acceptance.

Native public writes return a submitted result with an immediate proxy observation. A write is not complete until a fresh read-back reports the expected state. This applies to transport, track arm/mute, mix controls, and device insertion/removal as well as graph mutations. After an ambiguous result, read state before retrying.

Install the optional MCP server

MCP is optional and is not required for the direct Python example. Install it only after the extension is enabled and the read-only inspect check succeeds. From a checkout or matching full bundle with uv:

On macOS or Linux:

uv sync --frozen
BITWIG_MCP_GRID_BRIDGE_ENABLED=true uv run bitwig-mcp

In Windows PowerShell:

uv sync --frozen
$env:BITWIG_MCP_GRID_BRIDGE_ENABLED = 'true'
uv run bitwig-mcp

Configure the client to start the command from the absolute checkout path. See the MCP startup and client configuration guide for the JSON configuration, loopback host/port variables, and the startup contract. The server is local and its offline composition and audio-analysis tools do not require Bitwig. The exact MCP tools are documented in Agent tools.

Before any live MCP mutation, stop if the client is using the wrong checkout, tools/list differs from the running server, native capabilities is unavailable, or selected state does not match Bitwig. Begin with the read-only calls get_grid_capabilities, get_selected_device_state, and grid_song_state; refresh the relevant identity and revision before each later guarded operation.

The offline composition tools export a real Type-1 MIDI artifact plus a manifest and digest. They do not import MIDI into Bitwig, realize voices, create instruments, render audio, or save/load a project. The audio tools inspect files through ffprobe/ffmpeg; they do not capture from Bitwig or export a live render.

No Accessibility or Screen Recording permission is required by the bridge or MCP server. Separate desktop automation has separate permissions and is not a bridge capability.

Activation and troubleshooting

No listener or no response

  1. Confirm the extension was copied to the correct platform directory.
  2. Save work and restart Bitwig after replacing the extension.
  3. Check that only one Bitwig Grid Bridge controller instance is enabled.
  4. Check that the direct endpoint is local and that the MCP server is using the intended checkout.
  5. Re-read native capabilities and MCP tools/list; do not repeat a write until read-only state is available.

graph_available is false

A selected non-Grid device, an unsupported Grid device, a private-runtime mismatch, or an unavailable native graph can all produce this result. Keep using public host controls when their capability flags are true, or select a supported Grid device. Never guess package IDs, ports, module identities, or revisions.

Stale code after an install

Copying a new file and restarting only the public controller host may leave an old class definition in memory. Preserve the project, restart Bitwig, then recheck protocol 4 and the capability flags. A file hash alone cannot prove that the running controller has changed.

MCP tools differ from this page

The running server's tools/list response is authoritative. Check that the MCP process was started from the intended checkout and that BITWIG_MCP_GRID_BRIDGE_ENABLED=true is set. Do not treat old documentation, a historical 31-tool inventory, or an advertised 90-tool design as an implemented surface.

At any of these stop conditions, remain on the read-only path. Do not use a mutation to test loading, and after an ambiguous result inspect current state before retrying.

Historical evidence — tested build 0.2.0 on one macOS host (not a 0.2.1 verification)

Local macOS verification

The Apple Silicon machine running Bitwig 6.1.1 was exercised through a fresh stdio MCP client: 57 tools, native protocol 4. The installed extension SHA-256 was 2573efe49f9947725ad10c8a04d5d7ff76dbc16071b5326aa9b3804bcb68acab. This is evidence for that build and host, not compatibility with other releases.

Surface Exercised result
Public host controls Tempo, track mute, metronome action, and pan changed and were restored by read-back. Pan left gain unchanged; stale mix revisions were rejected.
Device lifecycle Catalog-resolved FX Grid inserted after Acid, observed in the chain, then removed; Acid-only chain and original selection restored.
Grid operations Temporary FX Grid exposed all graph capability flags. Analysis, additive module insertion, coordinate move, clear, and stale-revision rejection passed live read-back. Coordinate persistence across restart was not tested.
Display resolution 125 ms resolved to 0.125; Soft resolved to enum value 3; an unknown unit was rejected.
Patch sessions Preview, status, single-step apply, bounded control, and scoped parameter restore passed. The existing audio cable remained intact; an external move froze the affected session.
Host modulators Acid returned 12 native sources with observed names and mapping state. Source identity is not claimed: the native owner name is not a per-source identity.
Offline composition Plan/start/status/revise/export exercised. Independent MIDI decoding verified format 1, five tracks, released notes, scale membership, and every track ending at tick 31360. Serialized tempo yields approximately 27.999972 seconds for the 28-second plan. Stale export revisions were rejected.
Audio-file review WAV/MP3 analysis and comparison passed; attenuation-only RMS-matched WAVs were written and verified. The demo WAV is exactly 28 seconds, 48 kHz stereo, finite, non-silent, and has no decoded full-scale rail hits. These are technical checks, not listening approval.

The Java build passed with deprecation warnings treated as errors; the Python suite passed 107 tests. Bitwig remained in the background. Verification restored transport, track controls, selected-device parameters, and the device chain without saving the project. The saved demo project and WAV retained their pre-verification SHA-256 digests:

  • Interleave28.bwproject: 02456e9a4045ad5dde6a909192ab78d1cbe061644e5e0afbb1bf9cfa23b33b60
  • Interleave28.wav: a03005f0190fd1c3009e57e950ea50a85cacbd1a21fd41f3a45ce5ceac04cbfd

The temporary Grid fixture was removed. No live arranger editing, MIDI import, capture, render, or project-save capability is implied by these checks.

Capability boundaries

The bridge intentionally does not expose these native families:

  • arranger note, clip, and automation editing;
  • MIDI import or voice realization;
  • live capture;
  • audio rendering/export; and
  • project save, new, load, or delivery.

Bitwig's own UI can perform actions outside this list, but doing so is not MCP acceptance. Keep backups and project copies, and use the smallest guarded operation that satisfies the task.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.