System

13 tools, defined in tools/system.py.

Tool	Title	Access
`dump_log`	Read Server Log	read-only
`force_state_refresh`	Force Printer State Refresh	write
`get_firmware_version`	Get Firmware Version	read-only
`get_server_info`	Get Server Port Info	read-only
`get_session_status`	Get MQTT Session Status	read-only
`get_user_pref`	Get Sticky Preference	read-only
`pause_mqtt_session`	Pause MQTT Session	write
`rename_printer`	Rename Printer Device	write
`resume_mqtt_session`	Resume MQTT Session	write
`set_print_options`	Set Print Options	write
`set_user_pref`	Set Sticky Preference	write
`trigger_printer_refresh`	Trigger Printer Refresh	write
`truncate_log`	Truncate Server Log	write, destructive

dump_log

Read Server Log · read-only

Return the bambu-mcp server log.

WHEN to use: diagnose connection issues, tool errors, or unexpected printer behavior by reading the last lines of the server log. It is a server-level operation and takes no printer parameter.

Sibling disambiguation: dump_log reads the server log file and changes nothing. truncate_log empties that same file, so read what you need with dump_log first.

Parameters

tail_lines (integer, default 200): Number of lines to return from the end of the log (default 200). Reduce it to shrink the response. The value is not validated: 0 returns the whole file.

Returns

{"lines": [str], "total_lines": int, "log_path": str} on success: lines holds the last tail_lines log lines (newest last), total_lines is the number of lines returned (not the size of the whole file), and log_path is the absolute path to the log file. When the log file does not exist yet, the same three keys are returned with an empty lines, total_lines 0, and an added note string. Error: {"error": "Error reading log file: <exception>"}.

Notes

The log file is bambu-mcp.log in the bambu-mcp install directory (the repository root); log_path in the result gives its absolute path.

The log file captures entries at the current runtime log level (both root and bpm boot fixed at ERROR; no env var sets this). Use POST /api/set_log_level?level=DEBUG&bpm_level=DEBUG for full debug output, then POST /api/set_bpm_verbose?printer=<name>&verbose=true to also capture raw MQTT message payloads from bpm — see docs/operators-guide.md Debug-logging SOP.

This tool returns its dict as-is and does not itself gzip+base64 compress the response. If a very large tail_lines produces a response the MCP limit rejects, lower tail_lines. The REST fallback GET /api/dump_log returns the whole log file as text/plain and ignores tail_lines.

force_state_refresh

Force Printer State Refresh · write · needs user_permission=True

Send a push_all / ANNOUNCE_PUSH request to force the printer to re-broadcast its full state.

WHEN to use: printer state appears stale or fields are missing and you want the result as a dict.

WRITE GUARD: publishes ANNOUNCE_VERSION and ANNOUNCE_PUSH requests to the printer's MQTT request topic so it re-sends its full state. It changes no printer setting. With user_permission unset the tool changes nothing, does not call printer.refresh(), and returns the refusal naming that consequence.

Sibling disambiguation: force_state_refresh and trigger_printer_refresh make the same printer.refresh() call and differ only in return shape: this one returns a dict, trigger_printer_refresh returns a string.

Parameters

name (string, required): Configured printer name (see get_configured_printers).
user_permission (boolean, default false): Set to True only after the operator approves sending the refresh requests to the printer.

Returns

A dict. Success: {"success": True, "message": "State refresh request sent to '<name>'."}. Errors are {"error": str}: the refusal "Error: user_permission must be True to perform this action. <consequence>", "Printer '<name>' not connected", or "Error sending state refresh for '<name>': <exception>".

Notes

The tool calls printer.refresh(), which publishes ANNOUNCE_VERSION and ANNOUNCE_PUSH via MQTT, but only while the BPM service state is CONNECTED. In any other state (for example PAUSED) it sends nothing, and the tool still returns the success dict. Check get_session_status if state does not update.

get_firmware_version

Get Firmware Version · read-only

Return the current firmware version for the named printer.

WHEN to use: check which firmware a printer (and its AMS, when reported) is running, for example before deciding whether a firmware-dependent feature is available.

Sibling disambiguation: get_firmware_version returns the firmware versions alone. get_printer_info returns the model and serial number together with the firmware version.

Parameters

name (string, required): Configured printer name (see get_configured_printers).

Returns

{"firmware_version": str, "ams_firmware_version": str} on success. Both are strings and read "" (never None) until the printer reports them: firmware_version until the version handshake reply arrives, and ams_firmware_version also on a printer with no AMS. To detect a missing value test for the empty string, not None; call trigger_printer_refresh if firmware_version stays "". Error: {"error": "Printer '<name>' not connected"} when the printer has no live session.

get_server_info

Get Server Port Info · read-only

Return runtime port pool state for the bambu-mcp server.

WHEN to use: discover the actual REST API port at runtime before constructing an HTTP request URL (the REST API base URL is http://localhost:{api_port}/api), or to see which ports the shared pool has claimed.

Sibling disambiguation: get_server_info reports server-wide port usage, including every active MJPEG camera stream. get_stream_url returns the camera stream details for one named printer.

Args: none.

Parameters: none.

Returns

A dict on success:

api_port: TCP port the REST API is currently bound to (0 if not running).
api_url: convenience base URL, http://localhost:{api_port}/api.
pool_start: first port in the shared ephemeral pool (default 49152).
pool_end: last port in the shared ephemeral pool, inclusive (default 49351).
pool_size: total number of ports in the pool (pool_end - pool_start + 1; 200 with the default range).
pool_available: pool_size minus the number of claimed ports. It is understated when a claimed port lies outside the pool range (for example an out-of-range BAMBU_API_PORT).
pool_claimed: sorted list of all currently claimed port numbers (the REST API port plus all active MJPEG stream ports).
stream_count: number of active MJPEG camera streams.
streams: dict of {printer_name: {port, url}} for each active stream.

On failure: {"error": "Error retrieving server info: <exception>"}.

Notes

The bambu-mcp HTTP REST API and all MJPEG camera stream servers draw ports from a shared ephemeral pool anchored at port 49152 (IANA RFC 6335 Dynamic/Private range 49152-65535). Ports are allocated on demand and released when listeners stop.

The server also registers a Zeroconf/mDNS service (_bambu-mcp._tcp.local.) at startup so non-MCP clients can discover the port without calling this tool. See kb_get('bambu-http-system') for the TXT record schema.

Environment variables that control the pool:

BAMBU_PORT_POOL_START: override pool start (default 49152).
BAMBU_PORT_POOL_END: override pool end (default 49351).
BAMBU_API_PORT: preferred port for the REST API. It is tried first and is honoured even when it lies outside the pool; otherwise the pool is rescanned from pool_start (the scan does not continue from the preferred port).

Example, construct the REST API base URL::

info = get_server_info() base_url = f"http://localhost:{info['api_port']}/api"

get_session_status

Get MQTT Session Status · read-only

Return the current MQTT session state and connectivity info for the named printer.

WHEN to use: check whether a printer's MQTT session is connected or paused, for example after pause_mqtt_session or resume_mqtt_session, or when live state looks stale.

Sibling disambiguation: get_session_status reports on a printer that has a live session object and returns an error dict for one that does not. get_printer_connection_status inspects one printer by name and reports configured=False for an unknown name instead of an error.

Parameters

name (string, required): Configured printer name (see get_configured_printers).

Returns

{"name": str, "connected": bool, "service_state": str, "session_active": True} on success. connected is True only when the service state is CONNECTED; service_state is the BPM service state enum name (NO_STATE, CONNECTED, DISCONNECTED, PAUSED or QUIT); session_active is always True on success, because a printer without a live session returns the error shape instead. Errors: {"error": "Printer '<name>' not connected"} when the printer has no live session, or {"error": "Error getting session status: <exception>"} on failure.

get_user_pref

Get Sticky Preference · read-only

Return a sticky preference stored for a printer.

WHEN to use: before presenting a choice the user has made before, such as the print_file flags, the set_print_speed level or the start_ams_dryer settings, so the stored value can be offered as "(your preference)". Those tools' Notes name the keys they use.

Sibling disambiguation: get_user_pref reads one stored preference; set_user_pref stores one. Neither touches the printer. They are the same store as the REST route /api/user_prefs.

Parameters

name (string, required): Printer name the preference belongs to (see get_configured_printers). It is not checked against the configured printers.
key (string, required): Preference key, for example bed_leveling or ams0:target_temp.

Returns

{"key": "<name>:<key>", "value": <stored value or null>}. value is null when nothing is stored. Error shape: {"error": "Error reading preference: <exception>"}.

pause_mqtt_session

Pause MQTT Session · write · needs user_permission=True

Pause the MQTT session for the named printer, stopping telemetry updates.

WHEN to use: stop live telemetry from a printer without removing it, for example to quiet a session you are debugging. Undo it with resume_mqtt_session.

WRITE GUARD: unsubscribes from the printer's MQTT report topic and sets the session state to PAUSED, so live state stops updating. The printer configuration is retained. With user_permission unset the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: pause_mqtt_session only stops the incoming telemetry and keeps the configuration; resume_mqtt_session reverses it. disconnect_printer tears down the camera stream and the MQTT session while keeping the printer configured.

Parameters

name (string, required): Configured printer name (see get_configured_printers).
user_permission (boolean, default false): Set to True only after the operator approves pausing this printer's telemetry.

Returns

A string. Success: "MQTT session paused for '<name>'.". Errors are strings starting with "Error": the refusal "Error: user_permission must be True to perform this action. <consequence>", "Error: Printer '<name>' not connected." (the printer has no live session), or "Error pausing session for '<name>': <exception>".

Notes

Telemetry is the continuous stream of printer state updates (temperatures, fan speeds, print progress) received over MQTT. While paused, tools that read live state (get_printer_state, get_temperatures, etc.) will return stale data. Pausing an already-paused session is a no-op that still returns the success string.

rename_printer

Rename Printer Device · write · needs user_permission=True

Rename the printer device by sending it a RENAME_PRINTER command.

WHEN to use: change the device name the printer itself holds, as opposed to the local identifier this MCP uses.

WRITE GUARD: publishes a RENAME_PRINTER command (update.name) to the printer. It does not change the local identifier this MCP uses for the printer. Where the new name becomes visible (the printer's touchscreen, Bambu Studio) is expected behaviour that this code does not establish. With user_permission unset the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: rename_printer renames the printer device itself. The local identifier used by this MCP is determined by the name passed to add_printer and is not changed here. rename_sdcard_file renames a file on the printer's SD card, not the printer.

Parameters

name (string, required): Configured printer name (the local identifier, see get_configured_printers).
new_name (string, required): New device name to send to the printer.
user_permission (boolean, default false): Set to True only after the operator approves renaming the printer device.

Returns

A string on success: "Rename command sent to '<name>': printer display name set to '<new_name>'." (the publish call returned; delivery is not checked, since with the MQTT connection down the message is dropped silently, and the printer's acceptance is not confirmed). String errors: the refusal "Error: user_permission must be True to perform this action. <consequence>" and "Error renaming printer '<name>': <exception>". A printer with no live session returns a dict instead of a string: {"error": "Printer '<name>' not connected"}.

resume_mqtt_session

Resume MQTT Session · write · needs user_permission=True

Resume a paused MQTT session for the named printer.

WHEN to use: restart telemetry after pause_mqtt_session, or when a session has dropped and live state has stopped updating.

WRITE GUARD: re-subscribes to the printer's MQTT report topic to restart telemetry, and if the MQTT session thread has exited it opens a new MQTT session to the printer. With user_permission unset the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: resume_mqtt_session restarts telemetry for a printer that already has a session object; pause_mqtt_session is its opposite. get_session_status reads the resulting state without changing it.

Parameters

name (string, required): Configured printer name (see get_configured_printers).
user_permission (boolean, default false): Set to True only after the operator approves resuming or reconnecting this printer's MQTT session.

Returns

A string. Success: "MQTT session resumed for '<name>'.". Errors are strings starting with "Error": the refusal "Error: user_permission must be True to perform this action. <consequence>", "Error: Printer '<name>' not connected." (the printer has no live session), or "Error resuming session for '<name>': <exception>".

Notes

The success string is returned once the resume call completes without raising; it does not confirm that the session reached CONNECTED. Call get_session_status to check. If the session is not paused and its session thread is still alive, the call does nothing and still returns the success string; if that thread has exited, it starts a new session. If the session is paused but its MQTT connection has dropped while the session thread is still alive, the library leaves the state at QUIT and relies on paho's own reconnect: no new session is opened, and get_session_status reads QUIT until that reconnect completes.

set_print_options

Set Print Options · write · needs user_permission=True

Set one or more print option flags on the printer via MQTT.

WHEN to use: turn auto recovery and printer sound notifications on or off in one call.

WRITE GUARD: sends an MQTT print-option command to the printer for each flag you pass (auto_recovery, sound), which changes whether the printer resumes a print after a power loss and whether it beeps, and updates the local BPM config to match. With user_permission unset the tool changes nothing and returns the refusal naming that consequence.

Sibling disambiguation: set_print_options sets only the auto_recovery and sound flags together and returns a dict. set_print_option (singular) sets one option by name from a wider list (including the filament tangle, nozzle blob and air print flags) and returns a string.

Parameters

name (string, required): Configured printer name (see get_configured_printers).
auto_recovery (boolean or null, default null): If True, resume the print after a power loss (bpm also describes it as step-loss recovery); False disables that. None leaves the option unchanged.
sound (boolean or null, default null): If True, the printer beeps for notifications; False silences them. None leaves the option unchanged.
user_permission (boolean, default false): Set to True only after the operator approves changing these printer options.

Returns

A dict. Success: {"success": True, "options_set": {"auto_recovery": bool, "sound": bool}} listing only the options that were passed. Errors are {"error": str}: the refusal "Error: user_permission must be True to perform this action. <consequence>", "Printer '<name>' not connected", "No options specified. Provide at least one of: auto_recovery, sound" (both passed as None), or "Error setting print options: <exception>".

Notes

Calls printer.set_print_option(PrintOption, bool) once per option provided, auto_recovery first and then sound. If the second call raises, only the error dict is returned: the first option has already been published and its local config updated, and the result does not say which succeeded.

Each command carries the option keys accumulated by earlier print-option calls in this server process (bpm builds it from one shared module-level dict), so options you did not pass may be re-sent with their last-set values, possibly re-applying a value changed at the printer since. The same applies to set_print_option. {"success": True} means the publish call returned without raising, not that the printer received anything: bpm discards the publish result, and with the MQTT connection down paho drops the message without raising while the local config is still updated. Check get_session_status first.

set_user_pref

Set Sticky Preference · write

Store a sticky preference for a printer.

WHEN to use: after a tool call the user confirmed, to remember the value they chose, as the Notes of print_file, set_print_speed and start_ams_dryer direct.

Side effects: writes the value to the server's local preference file, replacing any value stored under the same key. Nothing is sent to the printer, so no user_permission is needed.

Sibling disambiguation: set_user_pref stores one preference; get_user_pref reads one back.

Parameters

name (string, required): Printer name the preference belongs to (see get_configured_printers). It is not checked against the configured printers.
key (string, required): Preference key, for example bed_leveling or ams0:target_temp.
value (string or integer or number or boolean or null, required): Value to store: a string, number, boolean or null.

Returns

{"key": "<name>:<key>", "value": <stored value>} on success. Error shape: {"error": "Error storing preference: <exception>"}.

trigger_printer_refresh

Trigger Printer Refresh · write · needs user_permission=True

Trigger a full data refresh by sending ANNOUNCE_VERSION and ANNOUNCE_PUSH via MQTT.

WHEN to use: printer state looks stale or fields are missing and the session reads as connected. Use sparingly, since frequent calls indicate a session issue.

WRITE GUARD: publishes ANNOUNCE_VERSION and ANNOUNCE_PUSH requests to the printer's MQTT request topic so it re-sends its full state. It changes no printer setting. With user_permission unset the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: trigger_printer_refresh and force_state_refresh make the same printer.refresh() call and differ only in return shape: this one returns a string, force_state_refresh returns a dict. refresh_nozzles refreshes nozzle information only.

Parameters

name (string, required): Configured printer name (see get_configured_printers).
user_permission (boolean, default false): Set to True only after the operator approves sending the refresh requests to the printer.

Returns

A string. Success: "Refresh triggered for '<name>'.". Errors are strings starting with "Error": the refusal "Error: user_permission must be True to perform this action. <consequence>", "Error: Printer '<name>' not connected." (the printer has no live session), or "Error triggering refresh for '<name>': <exception>".

Notes

The tool calls printer.refresh(), which re-requests all state from the printer, but printer.refresh() publishes only while the BPM service state is CONNECTED. In any other state (for example PAUSED) it sends nothing, and the tool still returns the success string. Check get_session_status if state does not update.

truncate_log

Truncate Server Log · write, destructive · needs user_permission=True

Truncate the bambu-mcp server log.

WHEN to use: start with a clean log after a debugging session. It is a server-level operation and takes no printer parameter.

WRITE GUARD: empties the server log file (bambu-mcp.log in the bambu-mcp install directory) to 0 bytes, permanently discarding every line it holds. With user_permission unset the tool changes nothing and returns the refusal naming that consequence.

Sibling disambiguation: truncate_log destroys the log contents; dump_log only reads the same file, so use it first to keep what you need.

Parameters

user_permission (boolean, default false): Set to True only after the operator approves permanently erasing the server log.

Returns

{"success": True, "log_path": str} on success, where log_path is the absolute path of the truncated file. Errors are {"error": str}: the refusal "Error: user_permission must be True to perform this action. <consequence>", or "Error truncating log file: <exception>".