Documentation menu
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

  1. Start the adapter from the intended checkout.
  2. Confirm the native extension reports protocol 4 and the expected host version/platform when live operations are required.
  3. Call tools/list and use read-only tools first.
  4. Read capabilities, selected state, project state, and graph state as needed.
  5. 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

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.