Skip to main content
Glama
CentauriMCP

CentauriMCP

by zant0p

CentauriMCP

A Model Context Protocol (MCP) server for safe, controlled remote operation of the Elegoo Centauri Carbon 3D printer.

⚠️ Safety First

This project provides controlled access to 3D printer operations with built-in guardrails:

  • Temperature monitoring - Auto-pause on thermal anomalies

  • Error detection - Monitors for filament runout, jams, motor failures

  • Rate limiting - Prevents rapid-fire commands

  • Audit logging - Every operation logged with timestamp and result

  • Pre-command validation - Verifies safe state before executing operations

Never leave a 3D printer unattended while printing. This tool assists with monitoring and control but does not replace proper safety practices.

Related MCP server: centauri-mcp

🎨 CANVAS Multi-Filament Support

The CC1 DOES expose its CANVAS trays. SDCP command 324 returns the full tray list — brand, material, colour hex, nozzle temperature range and whether a spool is present.

Correction: earlier versions of this README said the CC1 could not read slot configuration. That is wrong. Cmd 324 works, and it is how the app picks the right spool for a requested colour. It was written from the CC2's MQTT behaviour, which genuinely is different.

What works:

  • ✅ CANVAS module connection detection (AmsConnectStatus)

  • ✅ Reading every tray: brand, material, colour hex, temp range, loaded or not

  • ✅ Finding the tray holding a given colour

  • ✅ Telling the printer to feed a specific tray (slot_map on cmd 128)

  • ✅ Filament runout/jam monitoring during prints

  • ✅ Video stream for visual monitoring

What still doesn't work:

  • ❌ Modifying slot configuration via API

Picking the right spool for a colour

This is the part that is easy to get wrong, so it is worth stating plainly:

  • The gcode only ever names an extruder (T0), never a physical spool. On its own the printer picks a spool itself and ignores the colour you asked for.

  • Match by colour hex, not by material name. A CC1 commonly holds plain "PLA" in grey #898989, green #077747 and pink #F95D77 at once — matching by name picks whichever comes first.

  • Then tell the printer, with slot_map in the cmd 128 body:

    "slot_map": [ { "t": 0, "tray_id": 2, "canvas_id": 0 } ]

    Elegoo's own SDK calls this SlotMapItem { t, trayId, canvasId }. The CC1 supports it, the same way the CC2 does.

Note: status != 0 means a spool is present. Status 1 is "ready"; status 2 is also a loaded spool. Treating only status == 1 as present silently drops a loaded spool.

CANVAS hardware, for context

CANVAS is a four-channel material multiplexer (Happy-Hare style) with a filament multiplexer at the toolhead. Each spool carries an RFID tag storing brand, material, colour, diameter, weight and nozzle temperatures, so the printer can identify a spool by itself. The tag format was community-reverse-engineered (Elegoo's published spec was wrong): https://github.com/DnG-Crafts/ELG-RFID.

Full protocol detail: docs/SDCP_PROTOCOL.md.

Features

Phase 1: Read-Only Monitoring ✅

  • Real-time printer status (temperatures, position, state)

  • Live camera feed access

  • File listing (available prints)

  • Print history retrieval

  • Error code monitoring

Phase 2: Controlled Operations ✅

  • Pause/Resume/Stop print jobs

  • Start prints (with validation, and with CANVAS tray selection)

  • Fan speed control

  • Print speed adjustment

  • Chamber light control

Files

  • Upload a gcode to the printer's internal storage (1 MiB chunks)

  • List and delete files on the printer

  • Read the print task history

CANVAS

  • List the CANVAS trays and what is loaded in each

  • Find the tray holding a given colour

Architecture

  • Protocol: SDCP v3.0.0 (Smart Device Control Protocol) over WebSocket

  • Connection: ws://{printer-ip}:3030/websocket

  • Language: Python 3.10+

  • MCP SDK: mcp>=1.0.0,<2.0.0 (the 2.x line dropped the low-level Server.list_tools / Server.call_tool decorators this server is built on)

Full protocol reference: docs/SDCP_PROTOCOL.md — every command, the ack codes, the print/machine status codes, the CANVAS tray model, the upload protocol, and the traps that cost hours to rediscover.

Installation

# Clone the repository
git clone git@github.com:zant0p/CentuariMCP.git
cd CentuariMCP

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your printer's IP address

Configuration

Create a .env file with your settings:

# Printer Configuration
PRINTER_IP=192.168.100.114
PRINTER_PORT=3030
MAINBOARD_ID=60461c580103147000001c0000000000

# Safety Limits
MAX_NOZZLE_TEMP=300
MAX_BED_TEMP=110
COMMAND_RATE_LIMIT_MS=2000

# Logging
LOG_LEVEL=INFO
LOG_FILE=centauri-mcp.log

Usage

Running the MCP Server

python -m centauri_mcp.server

Example MCP Client Configuration

{
  "mcpServers": {
    "centauri": {
      "command": "python",
      "args": ["-m", "centauri_mcp.server"],
      "env": {
        "PRINTER_IP": "192.168.100.114"
      }
    }
  }
}

Available Tools

Once connected to an MCP client, you can use:

Read-only

  • get_printer_status() - Current temperatures, position, state, whether the chamber light is on

  • get_printer_attributes() - Model, firmware version, build volume, capabilities

  • get_camera_status() - Camera/CANVAS connection state and the video stream URL

  • list_files(path) - Available print files

  • get_print_history() - Historical print jobs

  • list_canvas_trays() - The CANVAS trays and what spool is in each

  • find_tray_by_color(color) - Which tray holds a given colour

Operations

  • start_print(filename, tray_id?, color?, bed_leveling?, bed_type?) - Start a print job (with validation). Pass tray_id or color to choose the spool.

  • pause_print() - Pause current print

  • resume_print() - Resume paused print

  • emergency_stop(reason) - Stop print immediately

  • set_fan_speeds(model, auxiliary, box) - Cooling fan speeds

  • set_print_speed(pct) - Print speed percentage

  • set_light(on) - Chamber light on/off

  • upload_file(local_path, remote_name?) - Upload a gcode to the printer

  • delete_files(filenames) - Remove files from the printer's storage

API Reference

Security

  • SSH key-based authentication for Git access

  • No credentials stored in repository

  • Local network only (no cloud exposure)

  • Deploy keys scoped to this repository only

Development

Branch Strategy

  • main - Production-ready code

  • dev - Active development and testing

Testing

# Run tests
pytest tests/

# Test WebSocket connection
python -m centauri_mcp.test_connection

Known Issues

  • Protocol field names contain spelling errors (e.g., CurrenCoord, RelaseFilmState) - must use exact spellings from spec

  • Video streaming limited to 1 concurrent connection by default

License

MIT License - See LICENSE file for details

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request to dev branch


Built with ❤️ for safe 3D printer automation

Last updated: 2026-07-12

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to monitor and control an Elegoo Centauri Carbon 3D printer via local network, supporting status checks, snapshots, and print control.
      26
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the Elegoo Centauri Carbon 3D printer that enables monitoring, control, and notifications via the SDCP 3.0 protocol over the local network.
      MIT