Cheat sheet
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: falseis 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.