cyberbrick-mcp
Summary: This MCP server drives the Bambu Lab CyberBrick desktop app over CDP, letting an AI agent plan hardware connections, author firmware configs, and flash devices end-to-end.
App health & control:
cb_health(CDP/version/bridge check),cb_launch(start app with debug port),app_logs(follow long flows like upgrades/pairing).Device inspection:
device_list,device_detail,board_info,device_status,device_ble_state,device_pool_state,device_request, plus full config readback with MD5 (device_config_get/block/read).Connectivity:
connect_scan_ports(enumerate available serial/BLE devices),connect_bluetooth(pair a board),connect_serial(select USB port),device_ble_heal(fix broken reconnect state).Firmware authoring: read/write the editor config (
firmware_config_get/set/edit/reset/load_template) and browse semantic docs for 60 editing actions (firmware_edit_actions).Flashing:
flash_check(preview upgrades),flash_config(burn config to a board),flash_mpy(MicroPython update, destructive),flash_firmware(full system firmware, destructive, needs a .bin),flash_test(send control commands).Project management:
project_state,project_list,project_create,project_import,project_export,project_rename,project_delete,project_load,project_save,project_open_editor.Window management:
window_list,window_close,window_close_others.Safety guardrails: destructive tools require
confirm: true, targets must resolve to exactly one device, secrets are filtered, and auth/cert/PIN/BIND flows are deliberately not exposed.
Drives the Bambu Lab CyberBrick desktop app over the Chrome DevTools Protocol, enabling device connection setup, firmware authoring and flashing, device status/config readback, project management, and CyberBrick hardware workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cyberbrick-mcp list my connected CyberBrick boards and show their status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, andflash_configwithhardwareMappings(which upgrades firmware first) requireconfirm: true, set only after the user explicitly agrees. For device write operations,targetmust 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_requestConnection planning:
connect_scan_portsFlash preflight:
flash_check(which firmware / MPY / loader upgrades ahardwareMappingsflash would trigger)Firmware reading:
firmware_config_get,firmware_edit_actions(semantic parameter docs for all 60 actions)Project reading:
project_state(page awareness +nextToolsprogressive 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 whenkill_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 theSET_DEVICE_CONFIGfile protocol; works with a single receiver and creates no new project),flash_mpy(destructiveHint: true),flash_firmware(destructiveHint: true),flash_testProject management:
project_create(6 built-in templates),project_import,project_rename,project_delete(destructiveHint: true),project_load,project_save,project_open_editorWindows:
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 testRelease version check:
node scripts/check_release.mjs [vX.Y.Z]Read-only path:
node scripts/verify_readonly.mjsServer and tool registration:
node scripts/mcp_list.mjsLocal smoke test (needs the running app):
node scripts/smoke.jsProject management smoke test (create → rename → export → import → load → save → delete):
node scripts/smoke_project.mjsProject management MCP E2E:
node scripts/mcp_e2e_project.mjsRC car end-to-end example (sender + receiver mappings → save → readback assertions → export;
--flashadds flashing and an LED test):node scripts/demo_rc_car.mjsAd-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 serverCDP 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 (
sanitizeinconnection.jsfilters by key name).Destructive tools (
flash_mpy,flash_firmware) carrydestructiveHintand requireconfirm: true— the agent must first explain the impact to the user (writes the board / reboots / can brick) and get consent.device_requestonly allows read-only methods (isInLoader,getDeviceById, andsendGetMessagefor commands on the read-only allowlist).cb_launchdoes not kill an already-running app by default (unsaved work would be lost); this needs an explicitkill_existing: true.Deliberately not exposed: BIND_DEVICE, SET_PRIVATE_KEY, certificate flows, PIN flows (see
ALLOWED_COMMANDSinsrc/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.
Bump the version in
package.json/package-lock.json(npm version X.Y.Z --no-git-tag-version),server.json(bothversionfields) andsrc/server.js.Add a
## [X.Y.Z] - YYYY-MM-DDsection toCHANGELOG.md.node scripts/check_release.mjs vX.Y.Z— must pass.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, environmentrelease). Trusted publishing can only be configured once the package exists, so for the very first release either publish once by hand or add anNPM_TOKENrepository 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
Available Tools
41 toolsapp_logsARead-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_infoARead-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_healthARead-onlyIdempotent
Check CyberBrick app health: CDP endpoint live, app version, renderer bridge access, device count. Call this first.
Inputs: no named parameters.
cb_launchADestructive
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 portsARead-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 portAIdempotent
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_healAIdempotent
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_stateARead-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_blockARead-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_getBRead-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_readARead-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_detailBRead-onlyIdempotent
Get detailed status for one device: connect state, loader mode, connection-pool entry. Read-only.
Inputs: device_id (required).
device_listBRead-onlyIdempotent
List devices known to the CyberBrick app (zustand deviceListStore). Read-only.
Inputs: no named parameters.
device_pool_stateBRead-onlyIdempotent
Inspect the internal Bluetooth connection pool (size + ids). Read-only.
Inputs: no named parameters.
device_requestARead-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_statusCRead-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 configARead-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 actionsARead-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 burnARead-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 upgradeADestructive
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 updateADestructive
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 projectADestructive
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 contentARead-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 projectsCRead-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 stateARead-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 windowsARead-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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLMs to interact with MIT App Inventor, AndroidBuilder, Kodular, or Niotron IDEs in real-time, controlling the Designer and Blocks workspace via Chrome DevTools Protocol.101MIT
- AlicenseNot gradedqualityAmaintenanceEnables the Pi coding agent to drive Chrome through DevTools, providing browser automation tools, persistent or isolated profiles, screenshots, page analysis, and bundled agent policies.5MIT
- AlicenseAqualityBmaintenanceEnables agents to inspect and drive Electron or Chrome/Chromium apps via the Chrome DevTools Protocol, exposing DOM snapshots, console logs, network requests, and gated interactions like clicking, typing, and navigating.673 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to perform bounded browser tasks by discovering or connecting to local Chromium/Electron endpoints, inspecting pages, and executing grounded page actions or Chrome DevTools operations.MIT