Documentation menu
On this page

The current source catalog registers 57 MCP tools. Inspect the running server's tools/list and native capabilities response; do not use a historical tool count or a copied extension file as live evidence.

Install and read-only check

make install-extension
python examples/automation/grid_bridge_demo.py inspect
python examples/automation/grid_bridge_demo.py graph

Save work and restart Bitwig after replacing the extension. Confirm native protocol: 4, host identity, and the relevant capability flags. A public ControllerHost restart can retain an old class definition in the same macOS session. No throwaway native attach probe is required.

Start the optional MCP server:

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

First MCP calls

get_grid_capabilities {}
get_selected_device_state {}
grid_song_state {}
grid_list_devices {}
get_grid_graph {}                 # only when graph_available is true
grid_analyze {}                   # topology, not sound proof

Native host calls

Goal Tool and guard
Transport grid_song_transport: fresh expected_project_token, operation, and confirm/cooperative.
Arm/mute grid_set_track_state: fresh project token, index 0..63, one or both booleans.
Mix grid_inspect_mix, then grid_set_mix with project token, mix revision, expected normalized value, and new value 0..1.
Devices grid_list_devices, then fresh non-null expected_selection_token for grid_insert_device or grid_remove_device.
Actions grid_list_actions, review an ID, then grid_invoke_action.

Native public writes return a submitted/immediate proxy observation. Read the matching state again before treating a write as complete.

Grid graph calls

get_grid_graph {}
search_grid_modules {"query":"osc"}
search_grid_modulators {"query":"lfo"}
grid_resolve_parameter_value {
  "module_id":"<current module>",
  "parameter_id":"<current parameter>",
  "display_value":"quarter note",
  "expected_revision":"<fresh graph revision>"
}

Graph mutations require exact current expected_revision and explicit authorization:

grid_insert_module {
  "package_id":"<catalog UUID>",
  "x":0,
  "y":0,
  "expected_revision":"<64-hex graph revision>",
  "confirm":true
}

Available direct graph edits are insert module/modulator, set parameter, connect, disconnect, move, and clear. Coordinates are -4096..4096. Read the graph after every mutation; a stale revision rejects the operation.

Preview-first sessions

grid_shape_start {"brief":"warmer, slower movement"}
grid_shape_status {"session_id":"<id>"}
grid_shape_apply {
  "session_id":"<id>",
  "revision":1,
  "confirm":true
}

For multi-operation topology work:

grid_patch_start {"nodes":[{"alias":"osc","package_id":"<UUID>","coordinates":{"x":0,"y":0}}]}
grid_patch_status {"session_id":"<id>"}
grid_patch_step {"session_id":"<id>","revision":1,"confirm":true}
grid_patch_restore {"session_id":"<id>","revision":2,"confirm":true}

Patch session revision and native graph revision are different. A failed read-back or external graph change freezes the session; it is not auto-replayed. Scoped restore is limited to parameters recorded by a completed parameter-only session.

Offline MIDI

grid_track_plan {"brief":"minimal techno, 142 BPM, F# minor, eight-bar phrases"}
grid_track_start {"brief":"minimal techno, 142 BPM, F# minor"}
grid_track_status {"session_id":"<id>"}
grid_track_revise {
  "session_id":"<id>",
  "revision":"<64-hex revision>",
  "scope":"phrase",
  "changes":{"density":0.3}
}
grid_track_export {"session_id":"<id>","revision":"<latest revision>"}

Export produces a real Type-1 MIDI file and digest-bound manifest. It does not import MIDI, realize voices, create instruments, render audio, or save a Bitwig project.

Offline audio

grid_audio_analyze {"path":"/absolute/path/input.wav"}
grid_audio_compare {
  "first_path":"/absolute/path/a.wav",
  "second_path":"/absolute/path/b.wav"
}

Comparison's optional match is whole-file RMS attenuation only and never amplifies a file. It is not live capture or audio rendering.

Recovery rules

  • Refresh the relevant project, selection, mix, or graph token before retrying.
  • Never blindly replay a timed-out submitted operation.
  • Read back native host writes; verified: false is not completion.
  • Preserve project copies before destructive graph clear or host-wide undo.
  • Treat native arranger note/clip/automation editing, MIDI import/voice realization, live capture, audio rendering/export, and project save/new/load/delivery as unavailable families.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.