orca-slicer-mcp

An MCP server that drives OrcaSlicer headlessly on a private Xvfb display, so an agent can import a model, slice it, and export G-code without a physical screen.

It exists because OrcaSlicer has no scripting API for slicing profiles the way its GUI does. Rather than click buttons by screen coordinate (fragile across versions and resolutions), this server drives OrcaSlicer through its single-instance IPC channel: a short-lived orca-slicer <arg> process forwards its argument over DBus to the already-running GUI. Model paths load via Plater::load_files; a small source patch adds an orca-cmd:export:<path> command that slices the current plate and writes the G-code straight to a file. No coordinate clicking, no file-chooser scripting.

Requirements

System binaries on PATH:

• orca-slicer 2.4.2, patched (see "OrcaSlicer patch" below)
• Xvfb
• openbox
• xdotool
• scrot

Python deps are declared in pyproject.toml (mcp, Pillow).

uv venv .venv
uv pip install --python .venv/bin/python -e .

OrcaSlicer patch

The DBus-command tools require a patched OrcaSlicer: patches/orca-mcp.patch adds one IPC command, orca-cmd:export:<path>, that slices the current plate and exports the G-code to <path> with no file dialog. It touches four files (InstanceCheck.{hpp,cpp}, Plater.{hpp,cpp}): a new EVT_EXPORT_GCODE_OTHER_INSTANCE event, its parsing in OtherInstanceMessageHandler::handle_message, and Plater::export_gcode_to(), which reuses the existing slice+export path (priv::export_gcode with FORCE_EXPORT).

Apply it in the AUR PKGBUILD (portable, survives OrcaSlicer updates): add orca-mcp.patch to source=()/sha256sums=() and

prepare() {
  cd "$srcdir/OrcaSlicer-${pkgver}"
  patch -p1 < "$srcdir/orca-mcp.patch"
}

then rebuild with makepkg. The patch applies cleanly with patch -p1 against the v2.4.2 source tree.

Single-instance IPC is only active when app.single_instance is true in ~/.config/OrcaSlicer/OrcaSlicer.conf; start_session sets this automatically before launching. (The --single-instance CLI flag is not used - it is not a valid OrcaSlicer 2.4.x option and is rejected by read_cli() before the IPC code runs.)

Running

.venv/bin/orca-slicer-mcp          # stdio MCP server

Register it with your MCP client, e.g. for Claude Code:

claude mcp add orca-slicer -- /home/USER/forge/orca-slicer-mcp/.venv/bin/orca-slicer-mcp

Tools

Tool	Purpose
start_session(display, width, height)	Launch Xvfb + openbox + OrcaSlicer; enable single-instance IPC; dismiss first-run/crash dialogs. Call first.
stop_session()	Terminate OrcaSlicer, openbox and Xvfb.
session_status()	Report running state and current windows.
screenshot()	Return the current screen as a PNG image.
import_model(path)	Load STL/OBJ/3MF/STEP/AMF/SVG into the running instance via single-instance IPC (Plater::load_files).
export_gcode(path)	Slice the current plate and export G-code to path via orca-cmd:export: (one IPC command); returns a header summary.
process_model(stl, gcode)	Convenience: import + export.
print_gcode(gcode, start=True)	Ship a local G-code to the Creality printer and start it (see Printing).
screenshot / click / type_text / press_key / zoom	Low-level primitives for dialogs not yet covered by the high-level tools.

Printing (Creality K1 Max)

print_gcode(gcode_path, start=True) closes the loop: it takes a G-code file this server just exported and gets it printing without you walking to the machine.

The printer's own web UI does expose starting a print, but only as a right-click/tap context-menu item per file — easy to miss and awkward on a phone. This tool drives the exact same two web actions programmatically:

1. upload — POST /upload/<name> (multipart, field file), and
2. start — a WebSocket set on /wsapi with opGcodeFile: "printprt:<gcode_dir>/<name>".

It reaches the Creality web UI through the docker container that serves it, bypassing the public oauth2-proxy gate — the local side only runs scp and ssh <host>; the HTTP upload and WebSocket start execute on the docker host (see creality_print_remote.py), the only machine on the printer's LAN.

Configuration (environment variables):

Variable	Default	Meaning
CREALITY_SSH_HOST	t580	SSH alias of the host running the Creality docker stack.
CREALITY_PROXY_CONTAINER	creality-proxy	Docker container serving the web UI; talked to directly, bypassing oauth2-proxy.
CREALITY_GCODE_DIR	/usr/data/printer_data/gcodes	Upload directory on the printer, used to build the printprt path.

Requires on the docker host: docker, curl, and Python with websocket-client. Pass start=False to stage a file without printing.

Why each moving part exists (hard-won lessons)

These are baked into session.py; do not "simplify" them away:

• A window manager is mandatory. Without one there is no _NET_ACTIVE_WINDOW; focus and window management silently misbehave. openbox is launched with a bundled openbox-rc.xml that makes every window undecorated and maximized.
• Commands travel over single-instance IPC, not the CLI action API. A second orca-slicer <arg> process passes CLI validation (the arg is a plain positional, not an option), reaches instance_check, and — because app.single_instance is enabled — forwards the whole command line over DBus to the running instance, then exits. --single-instance must not be passed: it is not a valid 2.4.x option and read_cli() rejects it before instance_check runs, so the sender would error out or spawn a second GUI.
• app.single_instance must be true before launch. It lives nested under the "app" object in OrcaSlicer.conf (not at the top level); start() sets it and OrcaSlicer preserves it across runs.
• Export completion is detected by the G-code file on disk, not by any GUI signal: export_gcode polls until the file stops growing across several samples (so a mid-write stall cannot yield a truncated read).
• Dialogs block the main window. The first-run SSL-certificate dialog, the update-check dialog, and — after any unclean exit — the crash "Restore" dialog all prevent the main window from being created. start() interleaves dismissing them with waiting for the main window, in one loop.
• The main window's title varies ("Unnamed Window", "*Untitled", a project name), so it is detected by size (>=90% of screen width), not by title.
• Every xdotool/scrot call has a timeout. A single blocked call (e.g. if the X server dies) would otherwise freeze every polling loop.
• Long-lived processes are owned by the server. They are spawned with start_new_session=True and held by the OrcaSession object; launching them from an ephemeral shell that then exits would kill them.

Testing

.venv/bin/python test_e2e.py

Runs the full import -> export against a sample STL on a fresh Xvfb and asserts a non-trivial G-code is produced.