Installation
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.
uvfor the optional Python MCP environment only.- Java 21 or newer and Maven when building the extension from source.
ffmpegandffprobefor the optional audio-file tools (brew install ffmpegon 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
- Confirm the extension was copied to the correct platform directory.
- Save work and restart Bitwig after replacing the extension.
- Check that only one Bitwig Grid Bridge controller instance is enabled.
- Check that the direct endpoint is local and that the MCP server is using the intended checkout.
- Re-read native
capabilitiesand MCPtools/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:02456e9a4045ad5dde6a909192ab78d1cbe061644e5e0afbb1bf9cfa23b33b60Interleave28.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.