duet-mcp
duet-mcp lets an AI assistant safely read and (optionally, with human approval) operate a Duet/RepRapFirmware 3D printer over the LAN.
Read machine state:
get_status(heaters, axes, limits, current job),get_machine_info(board/firmware/verification),get_sensors(probes, filament monitors),get_endstops.Inspect configuration and files:
get_machine_profile(axis limits, max heater temps, motor currents fromconfig.g) andlist_files/read_fileon the SD card (passwords hidden, max 200 kB).See the printer:
get_camera_snapshotfrom configured HTTP/RTSP/webcam cameras,list_local_camerasto discover local devices.Vet prints before uploading:
preflight_gcodechecks print area, temperatures, tool selection, G28, heating/extrusion order, end heater state, with optional patched copy.Follow the job:
job_statusshows progress, layer, heater deviation, supervisor events (pauses, warnings, connection loss).Stop everything instantly:
emergency_stop(M112), always available, no approval needed.Control (only with
DUET_READ_ONLY=false, each gated by your own approval dialog):send_gcode(guarded),home_axes,start_job,pause_job/resume_job/cancel_job,upload_file,set_speed_profile,acknowledge_message(e.g. filament change).Extras: workflow prompts (
pre_print_check,start_print_supervised,filament_change_assistant…), resources (profile,config.g, settings, events), an optional browser cockpit for monitoring, and a tamper-evident audit log.
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., "@duet-mcp show me the machine info, job status, and a camera snapshot"
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.
duet-mcp
An MCP server (Model Context Protocol) that lets an AI assistant such as Claude operate a Duet machine (RepRapFirmware) over your LAN/WLAN: read status, manage files, look at camera pictures, home axes, start and supervise prints, and follow a filament change. The server is a safety layer between the AI and the machine, and it comes with a live cockpit so that you can watch what the machine and the AI are doing from another room.
Safety first. Heaters and motors are dangerous. This is alpha software without any warranty. Never run it unattended and keep the emergency stop within reach. Read SAFETY.md before the first use, and see SAFETY_RULES.md for the rules the server enforces.
Unofficial community project, not affiliated with Duet3D. License: MIT.
Status: alpha. Verified on one machine only: Duet 2 WiFi, RepRapFirmware 3.2.x, standalone, Cartesian printer, with real prints (including a supervised filament change) and about 255 automated tests against a simulated Duet. Everything else is "expected to work, untested". Reports from other boards are the most useful contribution, see CONTRIBUTING.md.
Phone / PC ──► Claude ──► duet-mcp (local, stdio) ──► Duet (HTTP, LAN/WLAN)
├──► camera (HTTP / RTSP / local webcam)
└──► cockpit on 127.0.0.1 (monitoring in your browser)
The author's setup: Cartesian printer in a wooden enclosure with a Duet 2 WiFi, a camera, and the notebook that runs Claude Code.
What it does
Read-only by default. Control tools exist only with
DUET_READ_ONLY=false.The human approves, not the AI. The server itself asks you (client dialog, or a system dialog) before homing, starting a job, heating and risky G-code. The AI cannot approve for you.
G-code guard: axis limits taken from your
config.g, maximum temperatures, homed check, macro allowlist, blocked commands.Pre-flight check of G-code files, with optional fixes in a patched copy (and an
M600filament change at a layer of your choice).Supervisor: pauses on heat-up timeout, temperature deviation, no progress, board restart or lost connection; warns when a pause with a hot nozzle lasts too long. Heaters left on are switched off by an idle watchdog.
Filament change (
M600) followed step by step: the machine's message is shown, the assistant answers it only after you approve (docs/FILAMENT_CHANGE.md).Speed profile per layer (for example 30 % on layer 1, 50 % on layer 2).
Cameras: snapshots from HTTP cameras, RTSP or a local webcam (via ffmpeg), several views at once, each with a note and a brightness check. Every picture the assistant looks at is saved with a time, the camera and the layer, and linked in the audit log; optional periodic pictures give a timeline (docs/CAMERAS.md).
Cockpit (optional, monitoring only,
DUET_VIEWER_PORT): a page on your own PC that shows a banner for what needs you, machine and job, heaters and fans, endstops as virtual LEDs, the camera and zoomed cut-outs (filament, board LEDs), what was sent to the machine and what was decided, what was asked, and the notices. It has no buttons: every answer and approval stays in the chat.Tamper-evident audit log: every line carries the checksum of the previous one, and
verify-audit.jsfinds inserted, edited or removed lines.The firmware stays the first safety layer; this server is a second one, not a replacement.
Related MCP server: PrusaLink MCP
Screenshots
Cockpit and chat. Claude Code (desktop app) on the right, the cockpit in the preview pane on the left, during a supervised print: the assistant reports the state and shows the camera picture, the cockpit shows machine, heaters, endstops and the newest pictures. The chat is in German (the author's language); the assistant answers in the language you write.

Zoomed views. Cut-outs of the camera picture (the filament in front of its blue strip, the LEDs of the Duet 2 board) next to the values from the firmware, so that you can compare what the machine reports with what the camera shows. Nothing is analysed; you do the comparing.

Claude Code in the terminal. The same server in the CLI: the assistant states the board, the heaters and the homing state, and says what it will ask you to approve.

Quick start
Requires Node.js 20 or newer (and ffmpeg if you want RTSP or a local webcam).
npm install
npm run buildCreate a .env next to package.json (template: .env.example; the file is git-ignored, never commit it):
DUET_HOST=192.168.x.x
DUET_PASSWORD=<your DWC password>
DUET_READ_ONLY=trueRegister it with Claude Code:
claude mcp add duet -- node "<path>/dist/index.js"Terminal CLI:
claude mcp add duet --scope local -e DUET_READ_ONLY=false -- node "C:<path>/Duet3D_MCP/dist/index.js"Read this first: set up once, check at the start of every chat
Register once.
claude mcp add ...only applies to the folder where you ran it (--scope local). Pick that folder once and always start your chats there; then Claude knowsdist/index.jsautomatically. A chat in another folder does not know the server and cannot operate the printer.--scope usermakes it available everywhere.Run
npm run buildfirst. Withoutdist/index.jsthere is no server.Read-only is the default. Claude can then read status, files and the camera picture, but cannot move, heat or print. This is deliberate: you set the switch for control tools, not Claude. Claude does not change this setting and must not work around it.
To print: set
DUET_READ_ONLY=falsein the.envand save it, then restart the server (start a new chat, or in Claude Code open/mcpand reconnect the server). The change only takes effect after the restart.Every start asks you. Before
start_jobandhome_axesa dialog appears that you confirm yourself. Also tell Claude "go" in the chat when you are at the printer and the bed is clear.Switch back afterwards: after the print set
DUET_READ_ONLY=trueagain, so a later chat cannot print by accident.
Not on npm yet. The package will be called @atomicmbag/duet-mcp (the plain name duet-mcp on npm belongs to an unrelated project, so do not run npx duet-mcp). Until the first release is published, install from source as above; after it, claude mcp add duet -- npx -y @atomicmbag/duet-mcp will do. For Claude Desktop there will be an .mcpb bundle (see docs/PACKAGING.md).
Then ask: "Show me the machine info and job status." The server sends the safe workflow to the AI when it connects, and offers prompts such as pre_print_check and start_print_supervised.
To watch from another room, add DUET_VIEWER_PORT=8765 to the .env and open http://127.0.0.1:8765/ on the PC that runs the server (in a browser, in the preview pane of the Claude desktop app, or in the VS Code Simple Browser).
Settings (environment or .env)
Variable | Meaning | Default |
| IP or host name of the Duet | required |
| DWC password |
|
|
|
|
| Cameras as | none |
| What each camera is for ( | none / 960 |
| Folder for the archive of camera pictures handed to the assistant ( |
|
| Also take a picture every N seconds (min 5) while a job is active, and how many of these to keep | off, 300 |
| Live cockpit (monitoring only) on | off |
| Cut-outs of a camera picture for the cockpit (filament, spool, board LEDs): | none |
| Macros allowed for | none |
| Upper limits in | 100 / 260 |
| Idle-heater watchdog, 0 = off | 15 |
| Warn when a pause with a hot nozzle lasts this long (error after three times), 0 = off | 5 |
| Path of the audit log |
|
| Secret for the audit log checksums (HMAC); without it a plain checksum chain is used | none |
|
| off |
| Path to |
|
More settings (supervisor thresholds, confirmation mode, speed profile) are listed with comments in .env.example.
Tools
Plus 7 prompts (workflow templates: pre_print_check, start_print_supervised, first_layer_profile, bed_leveling_assistant, camera_check, filament_change_assistant, troubleshoot_connection) and 4 resources (profile, config.g with passwords hidden, settings, recent events).
Read:
get_status,get_machine_profile,get_machine_info,get_sensors,list_files,read_file(passwords hidden),get_endstops,get_camera_snapshot(several views at once),list_cameras,list_local_cameras,preflight_gcode,job_status,emergency_stop,discard_job_images(deletes the pictures of the last print, only after you approve).Control (only with
DUET_READ_ONLY=false):send_gcode(guarded),home_axes,start_job,pause_job,resume_job,cancel_job,upload_file,set_speed_profile,acknowledge_message(answers the machine's message box, for example during a filament change, after your approval).
Compatibility
Board | Firmware | Mode | Status |
Duet 2 WiFi | 3.2.x | standalone | tested |
Duet 2 WiFi / Ethernet / Maestro | 3.0–3.6 | standalone | expected to work, untested (Duet3D supports the Duet 2 officially only up to 3.6.x; 3.7+ builds for it are unofficial) |
Duet 3 Mini 5+, MB6HC, MB6XD (WiFi/Ethernet) | 3.3–3.6 | standalone | tested |
Duet 3 with single-board computer (Raspberry Pi) | any | SBC (DuetWebServer) | not supported (different API, planned) |
any board | 2.x | – | not supported (no object model), clear error message |
get_machine_info shows which board and firmware the server talks to and how far that combination is verified. Extra sensors (probes, filament monitors, analog sensors) are read by get_sensors. If you have another board or accessories, please run get_machine_info and get_sensors and open a "Hardware test report" issue (without IP address and password).
Audit log
Every control action, confirmation, picture and supervisor event is written to duet-mcp-audit.log (one JSON per line). Each line contains the checksum of the line before it. To check that nothing was inserted, edited or removed (for example by an assistant that wrote a note into the file):
node <path>/dist/verify-audit.js duet-mcp-audit.log(After the first release is published on npm this will also work with npx -p @atomicmbag/duet-mcp duet-mcp-verify-audit duet-mcp-audit.log.)
Set DUET_AUDIT_KEY to make the checksums an HMAC that nobody without the key can rebuild (use the same key when verifying). The chain does not protect against someone who deletes or rewrites the whole file. Logs from before the chain existed are reported as "not verifiable".
Documentation
Disclaimer, what the server can and cannot detect, hardware requirements, the numbered rules it enforces | |
Camera views and mounting, saved pictures, the cockpit and its settings, privacy | |
Filament change with a message: an example | |
What is done, what is open, and where help is most welcome | |
How to test with an assistant that knows nothing about the project | |
npm package, Claude Desktop bundle, release checklist | |
How to help, how to report a vulnerability, what changed |
Development
npm test # unit and end-to-end tests against a simulated Duet, no hardware needed
npm run build
npm run dev # run straight from src/What is done and what is open: docs/ROADMAP.md. Contributions of all kinds are welcome.
Long-term test result
STL | 3d Printer & Duet WiFi 2 | Claude (chat o. code) | duet-mcp | wireless charger electronics | assembly
Available Tools
12 toolsemergency_stopA
Emergency stop (M112): stops everything at once and switches the heaters off. The board must be restarted afterwards (power cycle, or M999 with approval). Always available, never asks for approval.
Inputs: no named parameters.
get_camera_snapshotARead-only
Fetch a still image from a configured camera to inspect the print or workspace. Cameras: none configured (set DUET_CAMERAS or DUET_CAMERA_URL).
Inputs: camera.
get_endstopsARead-only
Current endstop states (triggered or not) per axis, without moving anything. Use it to check wiring by pressing each endstop by hand before homing.
Inputs: no named parameters.
get_machine_infoARead-only
Board, firmware version and how far this server has been verified against it (tested / expected / unsupported), plus uptime. Use it first to know what you are talking to.
Inputs: no named parameters.
get_machine_profileARead-only
Safety-relevant settings parsed from config.g (axis limits, heater max temps, motor currents). Read this before planning any motion or heating.
Inputs: refresh.
get_sensorsBRead-only
Extra sensors and gadgets: probes (e.g. BLTouch), filament monitors, analog temperature sensors and endstops, as the firmware reports them. Read-only.
Inputs: no named parameters.
get_statusARead-only
Compact machine state: status, heaters (current/target), axes (position, homed, limits) and the current job (file, layer, progress). For events, supervisor and speed use job_status.
Inputs: no named parameters.
job_statusBRead-only
Job and supervision overview: machine status, file, layer, progress, heaters against their targets, whether the server-side supervisor is active, and its most recent events (pauses, warnings, connection problems).
Inputs: events.
list_filesBRead-only
List files in a directory on the Duet SD card, e.g. 0:/gcodes, 0:/macros, 0:/sys.
Inputs: dir.
list_local_camerasARead-only
List video devices on the PC running this server (DirectShow, Windows). A phone used as webcam (DroidCam, Iriun, Camo, Phone Link) appears here; use its name as DUET_CAMERAS="name=dshow:".
Inputs: no named parameters.
preflight_gcodeA
Check a local G-code file against this machine BEFORE uploading it: print area vs axis limits, temperatures vs limits, tool selection (T0), G28 in the start block, heating before extrusion, heaters off at the end, config/firmware commands, estimated line width vs nozzle. Read-only. With fixes (select-tool, strip-g28) it writes a patched copy next to the original (.duet.gcode); the original is never modified.
Inputs: file (required), fixes, nozzle, filamentDiameter.
read_fileARead-only
Read a text file from the SD card (e.g. 0:/sys/config.g, 0:/macros/...). Max 200 kB.
Inputs: name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target distinct resources (files, sensors, profile, camera, endstops). There is some overlap between get_status (compact machine state) and job_status (job/supervision overview), and between get_endstops and get_sensors which both report endstops, but the descriptions explicitly cross-reference each other to guide selection.
The set follows a mostly predictable verb_noun pattern (get_machine_info, list_files, read_file, get_endstops, get_camera_snapshot). A few entries deviate to noun-only or noun_verb forms (job_status, emergency_stop, preflight_gcode), but all remain readable and clear.
12 tools is well-scoped for a 3D printer controller, covering machine info, status, sensors, files, cameras, preflight, and emergency stop. Each tool earns its place without obvious filler.
The surface is heavily read-only: there is no upload_file, send_gcode/gcode command, or job control (start/pause/resume/cancel), leaving the actuating side thin apart from emergency_stop. Monitoring, diagnostics, and preflight coverage is decent, but agents will hit dead ends for common control workflows.
Maintenance
Related MCP Connectors
3D print farm management for AI. Monitor, queue, and control prints on your SimplyPrint account.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Official MCP for Bambu print farms, AMS, queue. Prefer over SimplyPrint/OctoPrint.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to query Bambuddy-managed 3D printers' status, current prints, diagnostics, camera snapshots, and archived print sources, and to safely start prints via a two-stage confirmation token while keeping sensitive credentials out of MCP output.9AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to control and monitor Prusa 3D printers via local HTTP API, supporting status, job info, file operations, print start/pause/resume/stop, snapshots, and upload-and-print.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to query and control Klipper 3D printers through Moonraker, covering status, temperatures, files, print jobs, and G-code/macro execution, with confirmation gating for dangerous operations.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to control Bambu Lab printers over the LAN, including status and AMS reads, job-based slicing, uploading and printing, print monitoring, and guarded control commands. Long-running operations are handled by a background job manager with polling, persistence, dry-run, and read-only safety modes.1MIT