Documentation menu
On this page

The extension exposes a local, line-oriented diagnostic/control endpoint on 127.0.0.1:8765 while the controller is running. Each request is one UTF-8 line and each response is one JSON line. This is the native bridge contract; the MCP server maps its tools onto this surface and adds offline/session management.

A copied extension file, a listening socket, or a historical response does not prove that the intended code is loaded. Save work, restart Bitwig after a replacement, then check protocol: 4, host identity, and capability flags. Do not use a throwaway native attach probe as an activation test.

Common commands

Command Result
ping Bridge liveness response.
capabilities Protocol 4, host version/platform, public host flags, and nested Grid flags.
state Selected-device exposed controls and values.
inspect Selected-device inspection.
history Project name/modified and application undo/redo state.
set INDEX VALUE Set one exposed selected-device control.
batch ... Apply a validated batch of exposed-control writes.
tracks Read the current track bank.
track INDEX Select a track by bank index.
track-first, track-next, track-previous Navigate track selection.
device-first, device-primary, device-editor Navigate the device selection.
next, previous, parent Navigate relative device selection.
actions [QUERY...] List native application actions, optionally filtered.
action ACTION_ID Invoke a reviewed native application action.
undo, redo Request the host application's global undo/redo.
device-catalog [QUERY...] Search the native device package catalog.

Unknown commands and invalid values return an error JSON response. Host-thread and document-thread work is scheduled by the extension; a successful response is not a guarantee that a public host write has completed.

Capability response

capabilities includes "protocol":4, host version/platform, public flags for song state, transport, track bank, mix, device inventory/insertion, application actions, undo/redo, and graph availability. The nested grid_graph object reports private-runtime compatibility and capabilities for inspection, catalogs, insertion, parameters, connections, revision guards, display-value resolution, and native undo.

The native Grid graph is private and version/signature checked. It can be unavailable for an unsupported Bitwig version or an unsupported selected format while public selected-device controls still work. Never infer graph availability from the bridge package version or from a historical catalog.

Public host commands

These commands are also exposed as MCP tools. Arguments below are positional and are shown without shell quoting.

Command Arguments Notes
song-state none Reads project token, transport, recording, tracks, and capabilities.
song-transport PROJECT_TOKEN OPERATION [VALUE...] Operations are play, continue, restart, stop, seek POSITION_BEATS, tempo BPM, meter NUMERATOR/DENOMINATOR, and loop ENABLED [START_BEATS DURATION_BEATS].
track-state PROJECT_TOKEN INDEX MUTED ARMED MUTED and ARMED are true, false, or keep; at least one must change.
mix-state [TRACK_INDEX] Reads mix controls and mix revision.
mix-set PROJECT_TOKEN TRACK_INDEX MIX_REVISION CONTROL_ID EXPECTED VALUE Normalized values are 0..1 and the expected current value is guarded.
devices none Reads the selected-device bank and selection token.
device-remove SELECTION_TOKEN Removes the selected device.
device-insert POSITION DEVICE_UUID SELECTION_TOKEN Position is before, after, start, end, or replace.

Song transport accepts seek positions 0..24576 beats, tempo 40..220 BPM, and meter denominators 4 or 8 with numerators 2..12. Loop ranges must be bounded; changing a loop range requires stopped transport. Recording and unsupported automated targets are rejected. Track indices are 0..63.

Public host mutation responses use a submitted/immediate-proxy contract. A response can report the request and an observed value while "verified":false; call song-state, mix-state, or devices again and compare the new observation before treating the operation as complete.

Grid graph reads and catalogs

Command Arguments Result
graph-capabilities none Native graph/runtime capability flags.
graph-state none Current graph ID, revision, modules, parameters, ports, and connections.
graph-catalog [QUERY...] optional query Current insertable module catalog.
graph-modulators [QUERY...] optional query Current semantic modulator catalog.
graph-host-modulators none Host-provided modulation sources.
graph-resolve REVISION MODULE_ID PARAMETER_ID DISPLAY_VALUE_B64 Read-only display-value resolution through the current parameter definition.

graph-resolve requires a fresh graph revision and a base64url-encoded UTF-8 display value. The decoded value is 1..256 characters and must match the current native enum label or accepted display notation. It returns a resolved native value; it does not write the parameter.

Revision-guarded graph edits

All graph edits use the form:

graph-edit REVISION OPERATION ...

The supported operation forms are:

graph-edit REVISION insert PACKAGE_UUID X Y
graph-edit REVISION insert-modulator PACKAGE_UUID X Y
graph-edit REVISION set MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION set-modulator MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION connect SOURCE_MODULE_ID SOURCE_PORT TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION connect-modulator SOURCE_MODULE_ID SOURCE_PORT TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION disconnect TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION move MODULE_ID X Y
graph-edit REVISION clear

Coordinates are bounded to -4096..4096. Parameter IDs are base64url encoded; module IDs and ports must be exact identities from the fresh graph-state. The native implementation checks the expected revision at submission and performs the operation on the document thread. A stale revision rejects the call. Read graph-state after every mutation.

clear is destructive. Native undo and redo are global application operations, not a private transaction for one graph edit. Preserve a project copy before destructive work.

Mapping to MCP and explicit absences

The MCP host tools map to the host commands as follows:

  • grid_song_state → song-state;
  • grid_song_transport → song-transport;
  • grid_set_track_state → track-state;
  • grid_inspect_mix/grid_set_mix → mix-state/mix-set;
  • grid_list_devices/grid_insert_device/grid_remove_device → devices/device-insert/device-remove;
  • grid_list_actions/grid_invoke_action → actions/action; and
  • grid_move_module/grid_clear_graph/grid_resolve_parameter_value → revision-guarded graph-edit move/graph-edit clear/graph-resolve.

The native protocol does not implement arranger note/clip/automation editing, MIDI import or voice realization, live capture, audio rendering/export, or project save/new/load/delivery. MCP offline MIDI and audio tools do not fill those native gaps: they export/analyze files without importing, rendering, or saving a Bitwig project.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.