Skip to main content
Glama

cyberbrick-mcp

English | 简体中文

An MCP server that drives the Bambu Lab CyberBrick desktop app (Electron) over the Chrome DevTools Protocol.

It covers the entire device setup workflow: hardware connection planning → firmware authoring → flashing.

Tools (41)

This server is a thin pass-through layer over the CyberBrick app: every tool calls the app's own API (store actions / device methods) and runs immediately. Exceptions: flash_mpy, flash_firmware, and flash_config with hardwareMappings (which upgrades firmware first) require confirm: true, set only after the user explicitly agrees. For device write operations, target must match exactly one device or the call is rejected.

Read-only / probing (readOnlyHint: true)

  • Infrastructure: cb_health, app_logs (app console logs, for following long flows such as upgrades or pairing)

  • Devices: device_list, device_detail, board_info, device_status, device_config_get, device_config_block, device_config_read (full readback + MD5), device_ble_state (live GATT / connectionCount state), device_pool_state, device_request

  • Connection planning: connect_scan_ports

  • Flash preflight: flash_check (which firmware / MPY / loader upgrades a hardwareMappings flash would trigger)

  • Firmware reading: firmware_config_get, firmware_edit_actions (semantic parameter docs for all 60 actions)

  • Project reading: project_state (page awareness + nextTools progressive disclosure), project_list, project_export

Write / flash (runs directly, MUTATING)

  • Launch: cb_launch (if the app is running without the debug port, it is only killed when kill_existing: true)

  • Connection: connect_bluetooth, connect_serial, device_ble_heal (repairs a NaN connectionCount so reconnects work without restarting)

  • Firmware authoring: firmware_config_set, firmware_config_edit, firmware_config_reset, firmware_config_load_template (loads a built-in template into the editor)

  • Flashing: flash_config (defaults to the SET_DEVICE_CONFIG file protocol; works with a single receiver and creates no new project), flash_mpy (destructiveHint: true), flash_firmware (destructiveHint: true), flash_test

  • Project management: project_create (6 built-in templates), project_import, project_rename, project_delete (destructiveHint: true), project_load, project_save, project_open_editor

  • Windows: window_list (read-only), window_close, window_close_others

Related MCP server: pi-browser-use

Verification scripts

  • Unit tests (no app or hardware needed): npm test

  • Release version check: node scripts/check_release.mjs [vX.Y.Z]

  • Read-only path: node scripts/verify_readonly.mjs

  • Server and tool registration: node scripts/mcp_list.mjs

  • Local smoke test (needs the running app): node scripts/smoke.js

  • Project management smoke test (create → rename → export → import → load → save → delete): node scripts/smoke_project.mjs

  • Project management MCP E2E: node scripts/mcp_e2e_project.mjs

  • RC car end-to-end example (sender + receiver mappings → save → readback assertions → export; --flash adds flashing and an LED test): node scripts/demo_rc_car.mjs

  • Ad-hoc call to any tool: node scripts/mcp_call.mjs <tool> '<json>' [...]

  • Re-extract template data (after an app upgrade): python3 scripts/extract_templates.py

Running

Requires Node.js 18+ and the CyberBrick desktop app on the same machine.

MCP client config (JSON), installed from npm:

{
  "command": "npx",
  "args": ["-y", "cyberbrick-mcp"]
}

From a local checkout:

npm install
node src/server.js        # stdio MCP server

CDP port

Defaults to 127.0.0.1:9223 (kept off the common 9222). Override with CB_CDP_HOST / CB_CDP_PORT. cb_launch starts /Applications/CyberBrick.app/Contents/MacOS/CyberBrick by default; override with CB_APP_BINARY.

Safety rules

  • Never reads or exports auth tokens, private keys or AES keys (sanitize in connection.js filters by key name).

  • Destructive tools (flash_mpy, flash_firmware) carry destructiveHint and require confirm: true — the agent must first explain the impact to the user (writes the board / reboots / can brick) and get consent.

  • device_request only allows read-only methods (isInLoader, getDeviceById, and sendGetMessage for commands on the read-only allowlist).

  • cb_launch does not kill an already-running app by default (unsaved work would be lost); this needs an explicit kill_existing: true.

  • Deliberately not exposed: BIND_DEVICE, SET_PRIVATE_KEY, certificate flows, PIN flows (see ALLOWED_COMMANDS in src/core/devices.js).

Releasing

CI (.github/workflows/ci.yml) runs on every push to main and every PR: tests on Node 18/20/22/24, a server start-up check, the version check and npm pack --dry-run.

Pushing a vX.Y.Z tag runs .github/workflows/release.yml: verify → publish to npm (with provenance) → publish server.json to the MCP Registry → create the GitHub Release from the CHANGELOG section. Each step skips itself if that version is already out, so a failed run can simply be re-run.

  1. Bump the version in package.json / package-lock.json (npm version X.Y.Z --no-git-tag-version), server.json (both version fields) and src/server.js.

  2. Add a ## [X.Y.Z] - YYYY-MM-DD section to CHANGELOG.md.

  3. node scripts/check_release.mjs vX.Y.Z — must pass.

  4. Commit, then git tag vX.Y.Z && git push origin main vX.Y.Z.

A tag with a suffix (v1.0.0-rc.1) publishes to npm under the next dist-tag and is marked as a pre-release.

One-time setup:

  • npm: on npmjs.com, add a trusted publisher for this package (GitHub Actions, workflow release.yml, environment release). Trusted publishing can only be configured once the package exists, so for the very first release either publish once by hand or add an NPM_TOKEN repository secret (an npm automation token); remove the secret once trusted publishing is on.

  • MCP Registry: nothing to configure. The workflow signs in with GitHub OIDC, which is valid for the io.github.<owner>/ namespace of the repository it runs in.

License

MIT

Available Tools

41 tools
app_logsA
Read-only

Read the CyberBrick app's renderer console, captured by this MCP server since it attached (ring buffer, 5000 lines; lines that mention tokens/keys/PINs/certs are never stored). Poll with since= to follow long tasks such as flash_config with hardwareMappings (upgrade → send config → pairing). Per-message B0 traffic and keepalives are hidden unless includeNoise. Read-only.

Inputs: grep, limit, since, levels, +1 more.

board_infoA
Read-onlyIdempotent

Aggregated board info for one device: firmware/loader versions, hardware string, project string, SN, board type — read via B0 SYSTEM_VERSION + GET_BOARD_INFO + GET_BOARD_TYPE.

Inputs: device_id (required).

cb_healthA
Read-onlyIdempotent

Check CyberBrick app health: CDP endpoint live, app version, renderer bridge access, device count. Call this first.

Inputs: no named parameters.

cb_launchA
Destructive

Launch the CyberBrick desktop app with the CDP debug port (9223). Reuses a reachable CDP endpoint. If the app is already running without the debug port, it fails unless kill_existing=true (the app enforces a single-instance lock) — killing it discards unsaved work, so get the user's OK first. NOTE: must run from an unsandboxed shell.

Inputs: timeout_ms, kill_existing.

connect_bluetoothAdd device via BluetoothA

Drive the app's real add-device flow (BluetoothDeviceManager.requestDevice — the same one the MyDeviceDialog UI uses): starts a BLE scan filtered to CyberBrick devices (companyIdentifier 17882, manufacturer data prefix [99]), then auto-selects the matching device so the chooser resolves without UI. After it resolves, the app marks the device and the caller can verify with device_list. MUTATING (pairs a device).

Inputs: deviceId, timeoutMs, deviceName.

connect_scan_portsScan connectable portsA
Read-onlyIdempotent

Enumerate Web Serial ports and Web Bluetooth devices currently available to the CyberBrick app. Read-only — does not pair or connect. Use this to tell the user what hardware can be connected right now.

Inputs: includeKnownDevices.

connect_serialSelect USB/Serial portA
Idempotent

Ask the app's main process to auto-select a Web Serial (USB-C) port (window.electron.ipcRenderer.autoSelectSerialPort, strategy "first") and return its metadata plus the BLE-connected board it belongs to (USB serial number = chip MAC, matched against each board's GET_DEVICE_WIFI_MAC). In this app the serial link only serves the USB flash (rescue flasher) feature — config, pairing, upgrades and every other device tool go over Bluetooth, so this does not make a board usable by the other tools. Opens nothing on the board.

Inputs: no named parameters.

device_ble_healA
Idempotent

Reset a non-finite (NaN/undefined) BluetoothDevice.connectionCount to 0 on live devices — the state markBluetoothDevice would have set — so the app's reconnect logic works again without power-cycling the board. No BLE I/O. Run before upgrades/pairing when device_ble_state shows connectionCountOk=false.

Inputs: no named parameters.

device_ble_stateA
Read-onlyIdempotent

Live BLE link state per device: GATT connected, store vs. manager status, pool membership, loader mode and the BluetoothDevice connectionCount. connectionCountOk=false means every reconnect (enterLoader during upgrades, BLE drops) will fail with RECONNECTION_INTERRUPTED — fix with device_ble_heal. Read-only.

Inputs: no named parameters.

device_config_blockA
Read-onlyIdempotent

Fetch one board-config file block (GET_DEVICE_CONFIG reqType=GET_FILE_BLOCK). Use after device_config_get reports file_size>0. Read-only.

Inputs: index (required), device_id (required).

device_config_getB
Read-onlyIdempotent

Board config file metadata (GET_DEVICE_CONFIG reqType=GET_FILE_INFO). file_size=0 means no config stored. Read-only.

Inputs: device_id (required).

device_config_readA
Read-onlyIdempotent

Read back the whole board config file (GET_FILE_INFO + every GET_FILE_BLOCK), trimmed to file_size, with its MD5 (compare with flash_config's md5) and the parsed config JSON. Read-only.

Inputs: device_id (required).

device_detailB
Read-onlyIdempotent

Get detailed status for one device: connect state, loader mode, connection-pool entry. Read-only.

Inputs: device_id (required).

device_listB
Read-onlyIdempotent

List devices known to the CyberBrick app (zustand deviceListStore). Read-only.

Inputs: no named parameters.

device_pool_stateB
Read-onlyIdempotent

Inspect the internal Bluetooth connection pool (size + ids). Read-only.

Inputs: no named parameters.

device_requestA
Read-onlyIdempotent

Call a read-only window.app.local method: isInLoader, getDeviceById, or sendGetMessage with a read-only B0 command (DEVICE_STATUS, GET_DEVICE_CONFIG, GET_BOARD_INFO, GET_BOARD_TYPE, GET_DEVICE_WIFI_MAC, SYSTEM_VERSION, MPY_PROJECT_INFO, MPY_CHECKSUM_INFO). Any other method or command is refused.

Inputs: method (required), args.

device_statusC
Read-onlyIdempotent

ADC / channel status vector (DEVICE_STATUS, 10 bytes). Read-only.

Inputs: device_id (required).

firmware_config_editEdit one config fieldA

Call a single firmware store action on the app store (e.g. updateReceiverChannel, updateSenderChannel, changeSwitchState). Immediately applies to the editor config. MUTATING. Use firmware_edit_actions first to get the exact arg signature (positional args, enums like receiverKey/actuator) for the action you want.

Inputs: action (required), args.

firmware_config_getGet current firmware configA
Read-onlyIdempotent

Read the current firmwareConfig from the app store (window.app.useFirmwareConfigStore). This is what would be burned to the board. Read-only.

Inputs: no named parameters.

firmware_config_load_templateLoad built-in template into editorA

Replace the editor config with one of the app's built-in project templates (same data as project_create, in the app's UI language). By default keeps the loaded project's id/name so project_save overwrites it; keepIdentity=false loads it as an unsaved new config. Marks the editor modified; nothing is written to the project list or board until project_save / flash_config. MUTATING.

Inputs: template (required), keepIdentity.

firmware_config_resetReset config to empty defaultsA

Clear the firmware config to empty defaults via the app store's resetFirmwareConfig. Immediately applies. MUTATING.

Inputs: no named parameters.

firmware_config_setSet full firmware configA

Replace the whole firmware config via the app store's setFirmwareConfig. Immediately applies to the app store (and the next burn). MUTATING — writes to the app's firmware config.

Inputs: config (required).

firmware_edit_actionsList firmware editing actionsA
Read-onlyIdempotent

Semantic documentation for the firmware-config store actions (window.app.useFirmwareConfigStore) — the surface behind firmware_config_edit. Returns enums (receiverKey, actuator, device, configType), grouped action names, and per-action arg signatures. Pass action= to get the doc for one action. Read-only, no app connection required.

Inputs: action.

flash_checkPreview upgrades for a hardwareMappings burnA
Read-onlyIdempotent

Dry-run of flash_config's hardwareMappings path: calls the app's checkDeviceConfigSync and reports, per board, which firmware / MPY / loader upgrades runSendConfigTask would run before sending the config and pairing. Nothing is written. Use it to get the user's consent for upgrades first. upgradeTargets is exactly what the run executes (the app's log may still mention a loader upgrade it then skips). Read-only.

Inputs: hardwareMappings (required), firmwareListId.

flash_configBurn firmware config to boardA

Write a firmwareConfig to the board. Default: the app's SET_DEVICE_CONFIG file protocol (FILE_INFO(md5,size) → chunked FILE_BLOCK via sendGetMessage) — works for a lone receiver, burns firmwareConfig if given else the current editor config, to exactly one target device (ambiguous or unmatched targets are refused). The device must be connected (else DEVICE_NOT_CONNECTED → call connect_bluetooth). Returns {ok, verified, bytes, chunkSize, blocks, md5, readback} — verified=true when the board reports the written size — or {stage, ...} on failure. Passing hardwareMappings switches to the app's runSendConfigTask (burns a saved project, needs a sender board; never creates a project). That path can also upgrade firmware / MPY / loader first — preview with flash_check and pass confirm=true only after the user approved those upgrades. Executes immediately — OVERWRITES the board's stored config. MUTATING / writes to hardware.

Inputs: target, confirm, firmwareConfig, firmwareListId, +1 more.

flash_firmwareFull system firmware upgradeA
Destructive

Run a full system firmware flash (SYSTEM_UPGRADE) via the app's updateLoaderFirmwareMpy with shouldUpgradeFirmware=true. Executes immediately — multiple reboots, CAN BRICK the device if interrupted. Requires firmwareBinaryB64: the MCP does not replicate the app's cloud package fetch (auth headers + certificate decryption are out of scope), so you must supply the .bin yourself (base64). Requires confirm=true after explicit user approval. DESTRUCTIVE.

Inputs: confirm (required), firmwareBinaryB64 (required), region, target, +1 more.

flash_mpyMicroPython firmware updateA
Destructive

Run a MicroPython firmware update via the app's updateLoaderFirmwareMpy (START_MPY_UPDATE). Writes mpy.img and REBOOTS the board. DESTRUCTIVE — requires confirm=true after explicit user approval. Default path upgrades to the built-in RC MPY (mpyType=1); passing userMpyConfig targets a design MPY. Experimental: the built-in path still needs live validation.

Inputs: confirm (required), region, target, mpyType, +4 more.

flash_testSend test/control commandA

Send a control/test command to a connected device via the app's sendTestCommand. Executes immediately — drives an actuator/output on the board. MUTATING.

Inputs: command (required), target.

project_createCreate project from templateA

Create a new CyberBrick project from a built-in template (the app's createProjectFromTemplate flow: template config + addFirmware). Templates: forklift, truck, forklift_and_truck, ball_car, official_remote, none, custom. MUTATING (adds a project to the app's list).

Inputs: template (required), name.

project_deleteDelete projectA
Destructive

DESTRUCTIVE: permanently deletes the project via the app store's deleteFirmware. This cannot be undone — the project config is removed from the app's persisted list. No confirmation is added by MCP.

Inputs: id (required).

project_exportExport project as JSON contentA
Read-onlyIdempotent

Export a project's config as JSON content — the same serialization the app's export uses (runtime fields stripped, version stamped). No save dialog; write the returned content to a file yourself. Read-only.

Inputs: id (required).

project_importImport project from JSON contentA

Import a project from its JSON content (the app's importProjectFromFileContent flow): validates config_version (rejects files newer than the app supports), forces design_id/region to app defaults, adds to the project list. Pass the file content as a string — read the file yourself first. MUTATING (adds a project).

Inputs: content (required), name.

project_listList projectsC
Read-onlyIdempotent

List CyberBrick projects via the app store's getShowList(): configId, type, configName, designLink, lastModifiedTime. Pass include=full to fetch one project's complete config body via getFirmwareById. Read-only.

Inputs: id.

project_loadLoad project into editorA

Load a project's config into the app's firmware editor store (setFirmwareConfig(getFirmwareById(id)) + setConfigType), the same thing the app does when you open a project. After loading, use firmware_config_edit to change parameters, then project_save to persist. MUTATING (replaces the current editor config).

Inputs: id (required).

project_open_editorOpen project editor windowA

Open the project editor (the app's openProjectEditor): loads the config into the editor store, then opens /project/edit?firmwareId= either in a new app window (default, via the app's createWindowWithPath) or by navigating the current window. MUTATING (loads config, opens window).

Inputs: id (required), target.

project_renameRename projectB

Rename a project via the app store's renameFirmware. MUTATING. Max 31 chars (app validation).

Inputs: id (required), name (required).

project_saveSave editor config as projectA

Persist the current editor config into the project list (the app store's updateFirmware: updates by id, adds if new) and mark the editor as saved. MUTATING (writes the project list).

Inputs: no named parameters.

project_stateGet project page stateA
Read-onlyIdempotent

Read the app's current context: active route (hash), project list summary, and editor state (isModified, configType). Returns a nextTools list of the tools relevant right now — call this first when working with CyberBrick projects, then act. Read-only.

Inputs: no named parameters.

window_closeClose an app sub-windowA

Close a CyberBrick app window by its windowId (from window_list). Uses the app's own closeSubWindow (window:close-sub-window IPC) — the same path as the window's close button; unsaved changes trigger the app's own confirm dialog, which the MCP does not bypass. The MCP-connected window cannot be closed (REFUSE_CLOSE_CURRENT). Each project_open_editor with target="new" opens one of these — close them to avoid window buildup. MUTATING.

Inputs: windowId (required).

window_close_othersClose all sub-windows except currentA

Close every CyberBrick app window except the one this MCP session is connected to. Use to clean up editor windows accumulated from project_open_editor. Unsaved changes surface the app's own confirm dialogs. MUTATING.

Inputs: no named parameters.

window_listList app windowsA
Read-onlyIdempotent

List the CyberBrick app's open windows: openWindows is the live truth (CDP page list with titles + hash routes), storeWindows is the window-state store's persisted id map (may be stale) — its ids are what window_close accepts. Also reports which window this MCP session is connected to (currentWindowId) and whether its editor has unsaved changes. Read-only.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with explicit warnings for destructive and mutating operations. Some overlap exists among device inspection tools (device_detail vs. board_info vs. device_status) and firmware/config editing paths (firmware_config_set vs. firmware_config_edit vs. project_save), but the descriptions generally clarify boundaries.

    Naming Consistency3/5

    All names use snake_case, but the structural conventions are mixed: some tools are resource_action (project_rename, device_list), others action_resource (flash_mpy, connect_bluetooth), and some have unique prefixes (cb_health, app_logs, board_info). The grouping is readable, but there is no single predictable naming pattern.

    Tool Count2/5

    At 41 tools, the surface is very heavy for an MCP server, even for a complex app-plus-hardware integration. Several tools are specialized or low-level, and the count exceeds the typical comfortable range without strong evidence that all are required for common agent workflows.

    Completeness4/5

    The tool set covers the domain broadly: project lifecycle, firmware config editing, device inspection, BLE/serial connection, flashing, health checks, logs, and window management. Minor gaps exist, such as explicit disconnect/unpair operations and higher-level device session cleanup, but core workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers