centauri-mcp

MCP server for the Elegoo Centauri Carbon 3D printer, built on the SDCP 3.0 protocol as documented by the OpenCentauri project (docs/software/api.md). Works over the local network — no cloud.

Features

Read-only (no approval needed)

Control (annotated so MCP clients require approval)

Related MCP server: 3D Printer MCP Server

Notification priority and sound

One global setting covers every alert the watcher sends — there is no per-event configuration:

set_notification_settings(priority=1, sound="cosmic")

Either argument may be given alone; the other is left unchanged. Settings are re-read on every send, so a running watcher picks up changes without a restart.

Sounds: pushover, bike, bugle, cashregister, classical, cosmic, falling, gamelan, incoming, intermission, magic, mechanical, pianobar, siren, spacealarm, tugboat, alien, climb, persistent, echo, updown, vibrate, none.

With nothing set, priority falls back to per-event defaults (pause and printer errors high, stop and complete normal) and the sound is your Pushover account default. Setting a global priority overrides those defaults everywhere.

Environment equivalents: PUSHOVER_PRIORITY, PUSHOVER_SOUND (the config file wins if both are present).

The watcher

start_monitor spawns centauri_mcp.watcher as a detached process. It outlives the MCP server and your client session, so alerts still arrive hours into a print with nothing open.

It holds a WebSocket to the printer and reacts to every pushed status message rather than polling a cache — a brief Complete -> Idle transition cannot slip between samples. Notifications fire on:

Each carries filename, layer, percent complete, and a camera snapshot unless started with with_snapshots=false.

Continuous vs one-shot

By default the watcher is continuous: after notifying you it keeps running, so subsequent prints are covered too. It stops only on stop_monitor, the stop flag, a kill, or a reboot.

Pass stop_after_print=true for one-shot mode — it shuts itself down once the print reaches Complete or Stopped, after the notification has been sent. A pause does not end it, since the print can still resume.

start_monitor(stop_after_print=True)

Run it standalone (e.g. from Task Scheduler at logon, so it covers prints started from the printer's own screen):

python -m centauri_mcp.watcher --ip 192.168.1.50

python -m centauri_mcp.watcher --ip 192.168.1.50 --exit-on-complete

State lives in ~/.centauri-mcp/:

Override the directory with CENTAURI_MCP_HOME. It deliberately avoids %LOCALAPPDATA%: the Microsoft Store build of Python virtualizes AppData into a per-package sandbox, which hides these files from you and from any other interpreter.

Install

git clone https://github.com/blanders2/centauri-mcp.git
cd centauri-mcp
pip install -e .

Register with Claude Code:

claude mcp add centauri-carbon -- python -m centauri_mcp.server

Configuration (environment variables, all optional)

• CENTAURI_IP — printer IP; skips discovery (recommended if your printer has a DHCP reservation). Without it, the first discovered printer is used.

• PUSHOVER_TOKEN / PUSHOVER_USER — enables phone notifications from the watcher (print complete / paused / stopped / errors, with camera snapshot attached). The detached watcher inherits these from the MCP server; to run it independently at boot, use set_pushover_credentials instead, which writes ~/.centauri-mcp/pushover.json.

• CENTAURI_MCP_HOME — override the watcher's state directory.

Example registration with env vars:

claude mcp add centauri-carbon -e CENTAURI_IP=192.168.1.50 -e PUSHOVER_TOKEN=xxx -e PUSHOVER_USER=yyy -- python -m centauri_mcp.server

Safety design

• Tools that can affect a running print carry MCP annotations (readOnlyHint: false, and destructiveHint: true for stop/delete), so clients prompt for approval before running them.

• stop_print and delete_files additionally require an explicit confirm=true argument — a bare call refuses and explains why.

• The dangerous reverse-engineered config G-codes (M8803/M8807, which can brick the printer) are deliberately not exposed.

• The printer allows only one concurrent MJPEG stream; get_snapshot enables the stream, grabs one frame, and releases it.

Protocol notes

• WebSocket JSON on ws://<ip>:3030/websocket; UDP discovery M99999 on port 3000; MJPEG camera on port 3031; HTTP multipart upload with MD5 check.

• Several SDCP field names are misspelled in the protocol itself (CurrenCoord, RelaseFilmState, ...) — the client handles both spellings.