Overall printer state: Klipper readiness, print job state and progress, temperatures, position, homed axes, and any active error message. Start here — this is the cheapest complete picture of the machine.

What this specific printer supports, discovered live: heaters and their real temperature limits, controllable fans, sensors, LEDs, output pins, filament sensors, axis travel, calibration features, QIDI-specific Klipper modules, Moonraker components present, and macro count. Call this before assuming a feature exists — QIDI ship a trimmed Moonraker and an extended Klipper.

The safety envelope this MCP server is enforcing: temperature ceilings, confirmation thresholds, jog/extrude caps, read-only and during-print flags, and which risk tiers require confirmation. Read this to understand why a call was refused.

Current temperature, target, and heater power for every heater, plus all read-only temperature sensors (including the Max4's chamber thermal-protection sensor) and temperature-controlled fans.

Toolhead position: raw kinematic position, the G-code position (offsets applied), which axes are homed, the active Z offset, and speed/flow factors.

Escape hatch for arbitrary Klipper status objects. Pass a list of object names (e.g. ['bed_mesh','probe','mcu']); omit to get the full object list instead. Use get_capabilities first to see what exists.

Detail on the current print job: state, filename, progress by both layer and file position, durations, filament used, estimated remaining time, and the slicer metadata for the running file.

The printer's live Klipper configuration as Moonraker reports it: either the resolved settings tree (section -> key -> value) or the list of section names. Pass a section name to get just that section — the full tree is large.

Every G-code command and macro this printer accepts, with descriptions where available. Includes QIDI's custom macros (PRINT_START, M4029 levelling, M603/M604 filament handling, CLEAR_NOZZLE, and so on). Filter with contains.

Recent G-code console history — the commands sent and Klipper's replies, exactly what the Fluidd console shows. The fastest way to see why something failed or what a macro actually did.

Moonraker's cached temperature history (roughly the last 20 minutes, 1 Hz) for every heater and sensor: temperatures, targets, and power. Use this to judge whether a heater is tracking its target or a thermal runaway is developing.

Host and service health: Moonraker/Klipper versions, the printer's OS and CPU, load, memory, uptime, throttle flags (undervoltage), MCU load and communication error counters. Use this when prints fail oddly — an undervoltage flag or MCU bandwidth saturation explains a lot.

Every non-read action this MCP server has taken on the printer this session, with risk tier, arguments, and outcome (including refusals). Use it to answer 'what did the agent actually do to my printer?'

Set a heater's target temperature. heater is 'extruder', 'bed', or 'chamber'; target is °C (0 turns the heater off). Returns immediately — the printer heats in the background; use wait_for_temperature to block until it arrives. Requires confirm=true. Refused if the target is outside the safety envelope, and while a print is running unless the server allows it.

Poll until a heater reaches its target (within tolerance) or the timeout expires. Does not change any target — set_temperature does that. Safe to call repeatedly; returns the temperature trend so you can tell whether heating is actually progressing.

Turn off every heater (extruder, bed, chamber) in one call. Always permitted — this is the safe direction — and the right thing to call when you are unsure of the machine's state or finishing a session. The QIDI Box's own heater (filament drying) is left alone unless also_box_heater=true, so a drying run is not ended by accident.

Home the printer. Omit axes to home all of them (G28), or pass e.g. 'xy' to home a subset. On the Max4, homing Z runs the inductive probe against the bed. Requires confirm=true. Blocked during a print.

Move the toolhead to absolute coordinates in mm. Supply any of x/y/z; omitted axes hold position. feedrate is mm/min (capped by policy). Axes must be homed and each coordinate must be inside the machine's travel. Requires confirm=true. Blocked during a print.

Jog the toolhead by a relative offset in mm (any of dx/dy/dz). The destination is computed and bounds-checked before moving, and a single jog is capped by policy. Requires confirm=true. Blocked during a print.

Adjust the live Z offset (baby-stepping), in mm — positive raises the nozzle. Use mode='adjust' to nudge relative to the current offset, or mode='set' for an absolute value. Applies immediately, including mid-print, which is the usual way to fix first-layer squish. Not persistent across restarts.

Manually extrude (positive) or retract (negative) filament, in mm. The hotend must already be at or above Klipper's min_extrude_temp (135 °C on the Max4) — heat it with set_temperature first. Capped per call by policy. Requires confirm=true. Blocked during a print.

Set the print speed override (M220) as a percentage, 10–200. Applies live to a running print. Slowing a print that is having quality trouble is a common fix.

Set the extrusion flow override (M221) as a percentage, 50–150. Applies live. Use sparingly — flow changes mid-print show up as a visible band.

Disable the stepper motors (M84). The toolhead can then be moved by hand, but the printer loses its homed position and must be re-homed. Refused while a print is running — it would abandon the job mid-air.

Start printing a G-code file already on the printer (path relative to the gcodes root, e.g. 'benchy.gcode' or 'projects/bracket.gcode'). Two-step confirmation: the first call returns the file's slicer metadata plus a token so you can check you are printing the right thing, and the second call with that token starts it. Refused if a job is already running.

Pause the running print. On the Max4 this runs QIDI's PAUSE macro, which parks the toolhead and retracts. Requires confirm=true and an active print.

Resume a paused print. Requires confirm=true and a paused job.

Cancel the running or paused print. This ruins the part — the job cannot be resumed afterwards. Two-step confirmation, and it reports how far along the print was so you can see what you are throwing away.

Past print jobs with status, duration, filament used and timestamps. Useful for 'did the last print succeed?' and for spotting a pattern of failures.

Lifetime totals for the machine: jobs completed, total print time, longest job, and total filament used.

The pending job queue: what is lined up to print next and whether the queue is started or paused.

Before printing or queueing: does what the QIDI Box records in its slots suit these files? Compares each file's filament type and colours (from its slicer metadata) with the material and colour recorded per slot, and says which slots could serve each one. Names may be loose ('benchy'); an ambiguous or unknown name is an error that lists candidates. Advisory only: it never blocks, and it does not claim to know which slot the printer feeds for which tool. Returns nothing to compare on a printer with no Box.

Add one or more G-code files to the shared print queue. Names may be loose ('benchy' finds benchy.gcode); an unknown or ambiguous name fails the whole call with the candidates. The first call (no confirm) shows what each name resolved to, its print time, and whether the Box's filament suits it; re-call with confirm=true to queue. This is the cooperative way to share the machine: when somebody else is printing, queue your file so it runs after theirs instead of competing for the printer. Requires confirm=true. If the queue is already 'ready' it auto-starts when the printer goes idle, so in that state this counts as starting a print and also needs the printer lease.

Remove jobs from the print queue by job_id, or clear the whole queue with all=true. Requires confirm=true.

Start or pause the shared job queue. action='start' releases it so queued jobs begin printing as soon as the printer is idle — that needs the printer lease, since it commits the machine. action='pause' holds them, which is always allowed: preventing surprise starts is the safe direction. Requires confirm=true. Neither affects a job that is already printing.

List G-code files on the printer with size, modified time, and (when scanned) estimated print time and filament use. Filter with contains, sort by name or modified time. This is where start_print's filenames come from.

Full slicer metadata for one G-code file: estimated time, filament length and weight, layer heights, per-object height, nozzle diameter, filament type, first-layer and chamber temperatures, thumbnails present, and the slicer used. Read this before start_print to confirm the file matches the loaded filament.

The file roots this printer exposes (gcodes, config, logs, timelapse) with their permissions. Tells you where you may read and write.

List one directory's immediate contents (subdirectories and files) under a root. Use this instead of list_gcode_files when you care about folder structure.

Upload a G-code file to the printer. Provide the content either as content (plain text) or content_base64 (for binary-safe transfer). Does NOT start a print — call start_print separately, deliberately. Requires confirm=true; set overwrite=true to replace an existing file.

Read a file off the printer as text (truncated to a byte budget so it cannot flood context). Works on any root: 'gcodes' for prints, 'config' for printer.cfg and friends, 'logs' for klippy.log. Use tail=true to read the end.

Delete a file from the printer. Two-step confirmation. Refuses to delete the file that is currently printing.

Move or rename a file/directory on the printer. Both paths include the root, e.g. source='gcodes/old.gcode', dest='gcodes/archive/new.gcode'. Requires confirm=true.

Copy a file/directory on the printer. Both paths include the root, e.g. source='gcodes/a.gcode', dest='gcodes/backup/a.gcode'. Requires confirm=true.

Create a directory on the printer, path including the root, e.g. 'gcodes/projects'. Requires confirm=true.

Delete a directory on the printer. Two-step confirmation, and the ticket lists what is inside first. force=true is required to delete a non-empty directory.

Every fan on the printer with its current speed and type: the part-cooling fan, the Max4's two auxiliary fans, the chamber circulation fan, and the firmware-managed hotend/board fans (which report but cannot be set).

Set a fan's speed as a fraction from 0.0 to 1.0. Use fan='part' (or omit) for the part-cooling fan; other names come from list_fans (e.g. 'auxiliary_cooling_fan', 'chamber_circulation_fan'). Firmware-managed fans (hotend, board) cannot be set.

Turn the chamber/case light on or off. Handy before taking a webcam snapshot.

Set one of the printer's output pins by name and value (0–1). On the Max4 these are 'caselight', 'beeper', and 'Polar_cooler' (the chamber air conditioner). Use list_devices to see what exists.

Set an RGB(W) LED strip's colour. Components are 0.0–1.0. On the Max4 the strip is 'RGB' (25 LEDs); omit index to set the whole chain.

Sound the printer's beeper. duration_ms is capped at 5000. Useful to get a human's attention at the machine.

Show a short message on the printer's screen (M117) and/or write one to the G-code console (M118), which is where a human watching Fluidd will see it.

Everything controllable or readable that is not a heater or an axis: fans, output pins, LEDs, filament sensors, and their current values. A quick inventory before poking at hardware.

Enable or disable filament runout detection. Disabling it removes the printer's protection against printing into thin air after the spool runs out — QIDI's own macros disable it briefly during filament changes. Requires confirm=true to disable; enabling is free.

Whether filament is currently detected, and whether the sensor is enabled.

The active bed mesh and saved profiles: the probed Z deviation grid, its range, and the mesh area. Reveals whether the bed is warped and by how much.

Probe the bed and build a new mesh. Takes several minutes on the Max4's 9x9 grid and moves the toolhead across the whole bed; the bed should be at printing temperature for a meaningful result. The mesh is active immediately but NOT saved to disk — use bed_mesh_profile to save it. Two-step confirmation.

Manage bed mesh profiles: action='load' to apply a saved profile, 'save' to persist the current mesh (this writes printer.cfg and RESTARTS Klipper), 'remove' to delete one, or 'clear' to drop the active mesh. Save/remove are two-step because they rewrite the config.

Level the Max4's two independent Z steppers against each other (Z_TILT_ADJUST). Probes the configured points and adjusts each Z motor until the gantry is square. Run this if first layers are thicker on one side. Requires confirm=true.

Read the probe's current state (triggered or open) without moving anything. On the Max4 this is QIDI's inductive 'probe_air' sensor.

Probe the same point repeatedly and report min/max/average/median/stddev. This is the diagnostic for 'is my probe repeatable?' — a stddev above ~0.01 mm means the probe or gantry has a mechanical problem. Moves Z only. Requires confirm=true.

Read every endstop's triggered/open state without moving. Use this to diagnose a homing failure — a switch already reading 'TRIGGERED' at rest is the usual culprit.

Probe the bed's screw positions and report how far, and which way, to turn each levelling knob. The Max4 has four screws. Manual bed levelling aid — the printer only measures; you turn the knobs. Requires confirm=true.

Run resonance testing with the toolhead accelerometer and compute optimal input shaper settings (SHAPER_CALIBRATE). The gantry is shaken hard through a frequency sweep — loud, and it must not be interrupted. Results are applied in memory; saving them rewrites printer.cfg. Two-step confirmation. Note: the Max4 also ships QIDI's own M901 macro for this.

Set input shaper frequency/type directly, without running a calibration sweep. Useful to apply values you already know. Applies in memory only.

Grab a still image from the printer's camera and return it for inspection. Use this to check on a print: whether the first layer stuck, whether there is spaghetti, whether the part came loose. This printer switches its case light off when the touchscreen sleeps, so an idle machine usually returns a black frame: rather than hand you an image with nothing in it, the tool refuses with error 'frame_too_dark' and tells you to call set_case_light first. Pass allow_dark=true only if you want the raw bytes regardless — never describe the contents of a frame returned that way.

The cameras this printer exposes, with their stream and snapshot URLs. On stock QIDI firmware the camera is a crowsnest ustreamer instance on port 8080.

EMERGENCY STOP. Immediately halts the printer: all heaters off, all motion stopped, Klipper enters a shutdown state (this is M112). Any running print is lost. Never blocked — no confirmation, and it works even in read-only mode. Use it the moment something looks wrong. Recovery afterwards needs restart_firmware.

Abort a heater WAIT that is blocking the queue (QIDI's breakheater). If the printer is stuck in M109/M190/M191 waiting to reach a temperature it will never reach, this releases the wait without an emergency stop — so no firmware restart is needed afterwards. Heaters keep their targets; use cooldown to actually turn them off. QIDI-specific: not available on stock Klipper.

Abort a running macro (QIDI's breakmacro). Use it when a macro is stuck or is doing something you want stopped — a levelling routine, a filament change, a purge — without the emergency stop's shutdown and firmware restart. The macro stops wherever it is, so the printer may be left mid-sequence (parked oddly, heaters on, filament part-loaded): check get_printer_status afterwards. QIDI-specific: not available on stock Klipper.

Resume the print that was interrupted by a power loss (QIDI's power-loss recovery, 断电续打). Moonraker rebuilds recovery G-code from its saved state and STARTS PRINTING from where it stopped. Only meaningful when the printer's saved state says a print was interrupted — check get_saved_variables for 'was_interrupted' first. Two-step confirmation, because it begins a real print. QIDI-specific: not available on stock Klipper.

FIRMWARE_RESTART: reset the microcontrollers and reload Klipper's config. This is how you recover from a shutdown or an e-stop, and how config changes take effect. Loses homing and any in-memory tuning. Requires confirm=true; refuses while a print is running.

RESTART: restart the Klipper host process (not the MCUs, not the OS). Reloads config without resetting the microcontrollers — a lighter action than restart_firmware, but it still ends any print. Two-step confirmation.

Run raw G-code on the printer — the escape hatch for anything the dedicated tools do not cover. Every line is screened: pure queries (M105, QUERY_ENDSTOPS, DUMP_TMC…) run with no confirmation, anything that acts needs confirm=true or the two-step token, and commands that bypass safety systems or rewrite config (SAVE_CONFIG, FORCE_MOVE, SET_KINEMATIC_POSITION, SET_TMC_CURRENT, PID_CALIBRATE…) are refused unless allow_dangerous=true AND the operator started the server with QIDI_ALLOW_DANGEROUS_GCODE=1. Heater targets, velocity/accel limits and coordinates are range-checked against the safety envelope. Prefer the dedicated tools — they add interlocks this cannot.

Run one of the printer's defined macros by name, with optional parameters. This is how you reach QIDI's own routines (e.g. M4029 bed levelling, CLEAR_NOZZLE, PRINT_START). Use list_gcode_commands to see what exists. Two-step confirmation, because a macro can do anything. The assembled command is screened exactly like run_gcode (deny-list, temperature and velocity/accel envelope); deny-listed macros are always refused here.

Read the tail of klippy.log — the definitive place to find why Klipper shut down, what an MCU error was, or what a failed print reported. Truncated to a byte budget.

Restart, stop, or start a systemd service on the printer (klipper, moonraker, crowsnest, …). Two-step confirmation. Restarting klipper or moonraker will drop this connection briefly and ends any print.

Reboot the printer's host computer (the whole OS, not just Klipper). Everything goes down for a minute or two. Two-step confirmation; refused during a print.

Shut down the printer's host computer. It will NOT come back until someone power-cycles the machine physically. Two-step confirmation; refused during a print.

Control the Max4's actively heated chamber: set a target in °C (max 65 by policy), or 0 to turn it off. The chamber is what makes ABS/ASA/PA printing work on this machine. Also reports the chamber circulation fan and the independent thermal-protection sensor. Requires confirm=true to heat.

Run QIDI's filament unload routine (M603). Heats the hotend to the given temperature, then retracts and ejects the filament. Give a temperature appropriate to the filament currently loaded (e.g. 250 for PLA, 280 for PETG). Two-step confirmation; refused during a print.

Run one stage of QIDI's filament load routine (M604). stage='heat' warms up and parks over the purge chute, stage='push' feeds filament in, stage='purge' extrudes until the old colour is flushed. Run them in that order, checking between stages — this mirrors what the printer's own screen does. Two-step confirmation; refused during a print.

Run QIDI's nozzle-cleaning routine (CLEAR_NOZZLE): heats up, moves over the purge chute and wipes the nozzle. Worth doing before a critical first layer. Requires confirm=true; refused during a print.

Run QIDI's own bed-levelling calibration (M4029) — the routine the printer's touchscreen calls, which heats the bed, probes, and stores the result. This is QIDI's equivalent of bed_mesh_calibrate plus Z-tilt, tuned for this machine. Takes 10+ minutes and normally restarts Klipper at the end. Two-step confirmation.

Persist the current live Z offset using QIDI's M1002 routine, so it survives a restart. Use set_z_offset to dial it in first, then this to keep it. Two-step confirmation, because it writes persistent state.

State of QIDI's Box (the multi-filament switcher): whether the firmware will actually use it, each unit's four slots with what the printer believes is in them (filament, colour and vendor decoded to names where QIDI's tables are readable), which slot is synced to the extruder, and the live box_extras object verbatim. If the Box is not working, problems says which of the conditions QIDI's macros test is false. Compare slots with the file's filament_type / filament_colors / referenced_tools from get_file_metadata before printing a multi-colour job. Returns box_count=0 on a machine with no Box.

Feed one Box slot toward the extruder with QIDI's E_LOAD SLOT= S=. Refused unless the printer lists E_LOAD: a real Max4 Box seen so far did not (it has MULTI_COLOR_LOAD, parameters unpublished), so on it this tool says so and sends nothing. slot is 0-based across the whole Box (unit 1 = slots 0-3, unit 2 = 4-7, ...). Refused unless the firmware will actually act on the Box (see get_box_status problems), the slot exists, and no tool change is running; empty-slot and already-loaded conditions are shown on the ticket for you to weigh. Two-step confirmation; refused during a print. Not yet verified against a physical Box: run docs/guides/box-first-contact.md first. To unload, use unload_filament -- QIDI's M603 already calls E_UNLOAD for the extruder.

Change one Box setting QIDI stores in saved variables: 'enable_box' (the firmware's master switch for Box handling), 'auto_read_rfid' (read the spool tag when a spool is inserted) or 'auto_reload_detect' (on a filament runout, run QIDI's AUTO_RELOAD_FILAMENT -- the Box feeds filament by itself). Needs a detected Box, refused during a print, and always needs confirm=true because there is no free direction: switching auto-reload on makes the machine feed filament unattended, and switching enable_box off makes the firmware ignore the Box. Reads the value back and reports whether it took. Slot contents and box_count cannot be set here.

Search the filament profiles, colour swatches and vendors the printer itself knows (its officiall_filas_list.cfg). Use it to find the exact name to give set_box_slot_filaments. query filters profiles by words in their name or type ('petg', 'matte', 'cf'); leave it empty for all of them. Colours are the printer's fixed swatches, each with a plain-English name.

Tell the printer what filament is in each Box slot, in plain words. assignments is a list like [{"slot": 0, "filament": "PLA Matte", "color": "black"}, {"slot": 1, "filament": "PETG", "color": "#1353AB", "vendor": "Generic"}]. slot is 0-based across the Box (unit 1 = slots 0-3). Filament and vendor are names or ids from list_box_filament_options; color is a colour word, #RRGGBB or swatch id, and lands on the nearest of the printer's own swatches. Only the fields you name change; everything else is kept. The first call (no confirm) shows exactly what each name resolved to and what would be written; re-call with confirm=true to write it, and the values are read back. This labels spools for the printer; it moves no filament and does not change whether a slot holds filament. Refused during a print. Not yet verified on a physical Box.

The printer's persistent saved variables (save_variables.cfg): Z offset, power-loss-recovery state, Box slot assignments, feature toggles, and the last printed file. Read-only view of what the firmware remembers across restarts.

Turn the Max4's chamber cooler ('Polar_cooler' — the active chamber air-conditioning) on or off. Used for PLA in a warm chamber, where you want the chamber cooler rather than hotter.

QIDI's built-in filament profiles as configured on this printer, including the recommended drying temperature and time per material from the machine's own drying table. Useful for answering 'how should I dry this spool?'.

Report the Max4's AI failure detection: whether spaghetti ('noodle') and foreign-object detection are enabled, their sensitivity, and the last verdict the camera service reported. Read-only. Note a zero count from a DISABLED detector means 'nothing ever reported', not 'the bed is clear' -- check the enabled flags before trusting it as evidence of anything.

Enable or disable one of the Max4's AI failure detectors: type 'noodle' (spaghetti) or 'foreign' (debris on the plate), optionally setting sensitivity to LOW/MEDIUM/HIGH. Worth enabling before a long unattended print. Turning a detector ON is free; turning one OFF removes a safety net and needs confirm=true. This only flips the firmware flag -- it cannot start QIDI's camera service, so verify with get_ai_detection_status afterwards.

Who is currently driving this printer, if anyone. Returns the holder's name, their stated reason, and how many minutes are left, plus whether it is you. A print started at the touchscreen or from Fluidd shows as a manual-print claim (manual=true) held by nobody. Call this first when a write is refused with 'lease_held', and before starting any long job. Reports coordination as unavailable on a printer whose Moonraker has no database component.

Claim this printer for yourself, so other agents are refused mutating actions while you work. Give a short human reason ('bracket v3, ~40 min') — the point is that whoever gets blocked can see who to talk to. Refused if somebody else holds it. Expires on its own so a forgotten lease cannot strand the machine; renew it with renew_printer_lease for long jobs. This is cooperative: it does not stop the printer's own touchscreen or Fluidd.

Extend your own lease, for a job that is taking longer than planned. Refused if you do not hold it, or if it already lapsed and somebody else took it.

Give the printer back when you are finished. Do this rather than letting the lease expire — the next person should not have to wait out your timeout.

Force-release SOMEBODY ELSE's lease, for when its holder has clearly gone away and the machine is stranded. Two-step confirmation, and the break is recorded in the audit log with your name. Check get_printer_lease and look at the machine first: if a print is actually running, breaking the lease does not stop it, and cancel_print or emergency_stop is what you want. On a manual-print claim (a print started at the touchscreen, shown with manual=true) this takes the print over: the claim becomes yours so you can then pause or cancel it.