Integration overview
On this page
This section is for MCP clients, scripts, and orchestration layers. It defines the supported transport, startup contract, tool entry points, and safety gates. For producer-facing procedures, use the Producer guide.
Supported integration path
MCP client
│ MCP stdio
▼
Python adapter: native tools, guarded sessions, offline MIDI/audio tools
│ UTF-8 command line → JSON response over 127.0.0.1:8765
▼
Bitwig Grid Bridge extension
│ serialized host/document-thread calls
▼
Bitwig Controller API 25 (public host API)
The Java extension is authoritative for live Bitwig state. Direct scripts may use the same newline-command/JSON-response endpoint without MCP. Private Grid bindings are version/signature checked for Bitwig 6.1.1 and fail closed when unsupported. The native extension reports protocol 4.
The MCP source currently registers 57 tools. This is a source catalog, not live
acceptance; inspect the running server's tools/list and native capabilities
responses for the session in use.
Start the adapter
From a source checkout or matching full bundle:
uv sync --frozen
BITWIG_MCP_GRID_BRIDGE_ENABLED=true uv run bitwig-mcp
Example MCP client configuration:
{
"mcpServers": {
"bitwig-grid-bridge": {
"command": "uv",
"args": ["run", "--project", "/absolute/path/to/bitwig-grid-bridge", "bitwig-mcp"],
"cwd": "/absolute/path/to/bitwig-grid-bridge",
"env": {
"BITWIG_MCP_GRID_BRIDGE_ENABLED": "true",
"BITWIG_MCP_GRID_BRIDGE_HOST": "127.0.0.1",
"BITWIG_MCP_GRID_BRIDGE_PORT": "8765"
}
}
}
}
The adapter keeps stdout reserved for MCP messages. Capture logs through the client's stderr facility. Offline composition and audio-file analysis can run without Bitwig; native host and graph tools require the enabled extension.
Startup and activation contract
- Start the adapter from the intended checkout.
- Confirm the native extension reports protocol 4 and the expected host version/platform when live operations are required.
- Call
tools/listand use read-only tools first. - Read capabilities, selected state, project state, and graph state as needed.
- Refresh project, selection, mix, and graph identities before every guarded mutation.
After copying an extension, save work and restart Bitwig deliberately. A public ControllerHost restart can retain an old class definition in the same macOS session. A copied file, package version, or historical inventory is not proof that the running controller loaded the intended code. Do not use a throwaway native attach probe. Native host writes return submitted/immediate proxy observations; read the resulting state before continuing.
If the extension is unavailable, offline tools can still be useful, but no live state may be inferred from static or historical evidence. No external UDP socket is part of the current MCP startup contract.
First calls
For a live session, begin with:
get_grid_capabilities {}
get_selected_device_state {}
grid_song_state {}
Call get_grid_graph and grid_analyze only when the capability response
reports a supported graph for the selected device. A false graph_available
can coexist with usable public selected-device controls.
For device edits, inspect grid_list_devices and its bounded-window metadata,
then pass its fresh non-null selection_token as expected_selection_token to
grid_insert_device or grid_remove_device. For graph edits, read the fresh
expected_revision and authorize one operation at a time. For transport,
track, and mix writes, use the current project token/mix revision and verify
with a fresh read-back.
For offline music, use grid_track_plan or grid_track_start, review/revise,
and export a Type-1 MIDI artifact plus manifest. For audio files, use
grid_audio_analyze or grid_audio_compare; these do not capture or render
from Bitwig.
Reference pages
- Workflow playbook: safe end-to-end tool sequences and completion evidence.
- Tool reference: current MCP names, arguments, and mutation classes.
- Data and safety: identities, ranges, revisions, and recovery.
- Protocol and lifecycle: native protocol 4 and command semantics.
- Automation scripts: direct bridge use without MCP.