PrintMCP

<div align="center"> <img src="docs/img/printmcp-logo.png" alt="PrintMCP" width="480">

From "I want to print a coffee cup" to a finished print — driven by your AI agent.

PrintMCP is a Model Context Protocol server that automates the entire 3D-printing pipeline: find a model, slice it to G-code, and print it — all through tools an AI assistant can call.

🌐 View the website → — interactive demo, pipeline visualization, and full documentation.

If PrintMCP is useful to you, please ⭐ star the repo — it helps others find it.

</div>

---

🧭 The pipeline

PrintMCP is built in three levels. Each level is a group of tools, and together they form one continuous workflow from a vague idea to plastic on the bed.

flowchart LR
    Start(["🗣️ User request"]) --> S1
    subgraph L1["1 · Source — Thingiverse"]
        direction TB
        S1["search_models"] --> S2["get_model"] --> S3["download_model"]
    end
    subgraph L2["2 · Slice — Cura / OrcaSlicer"]
        direction TB
        SL["cura_slice_model"]
        OR["orca_slice_model / orca_list_profiles"]
    end
    subgraph L3["3 · Print — OctoPrint"]
        direction TB
        P1["upload_file"] --> P2["start_print"] --> P3["get_job"]
    end
    S3 --> SL --> P1
    P3 --> Done(["✅ Finished print"])

| Level | Scope | Backend | Status | |:-----:|-------|---------|:------:| | 1 · Source | Search for and download 3D model files | Thingiverse REST API | ✅ Implemented | | 2 · Slice | Slice models into printer-ready G-code | Ultimaker Cura (headless CuraEngine) or OrcaSlicer | ✅ Implemented | | 3 · Print | Upload, start, monitor, and control prints | OctoPrint REST API | ✅ Implemented |

---

📑 Table of contents

• ✨ Highlights
• 📚 Documentation
• 🛡️ Safety model
• 🧰 Tool reference
• 📦 Requirements
• 🚀 Quick start
• ⚙️ Configuration
• 🔌 Register with an MCP client
• 💡 Example: coffee cup to print
• 🗂️ Project structure
• 🧪 Development
• 🗺️ Roadmap
• ⚖️ Model licensing
• 📄 License

---

✨ Highlights

• One server, the whole pipeline. Search → download → slice → print, without leaving your assistant.
• License-aware sourcing. Every model's license is surfaced before you download, so you don't misuse it.
• Real slicing, real estimates. Slice with Ultimaker Cura's CuraEngine or OrcaSlicer (CLI, native or Flatpak), and report the true print time and filament usage from the engine itself.
• Safe by default. Tools that physically actuate the printer (heaters, motors) refuse to act unless you explicitly pass confirm=true — see Safety model.
• Structured or human output. Every tool accepts response_format (markdown or json).
• Zero-secret-in-output design. Credentials live in .env and are sent only to the services they belong to.

---

📚 Documentation

Full guides, a per-tool reference, and step-by-step tutorials live in docs/.

| Start here | Then | |------------|------| | 📖 Documentation hub | the index of everything below | | 🚀 Getting Started | install, configure, connect a client | | ⚙️ Configuration | every env var + where files are stored | | 🛡️ Safety Model | how confirm=true protects your machine | | 🔧 Troubleshooting | common errors → fixes | | 🏛️ Architecture | how it's built (for contributors) |

Tutorials — learn to 3D print by chatting with your assistant:

1. Find Something to Print
2. Get It Print-Ready
3. Send It to Your Printer
4. From Idea to Object

For developers — tool reference & API: the shared invocation contract, plus per-level details for Thingiverse, Cura, and OctoPrint.

---

🛡️ Safety model

[!WARNING] Level 3 drives a real machine. A bad tool call could heat a nozzle, move an axis, or abandon a print.

To prevent accidents, every physical-actuation tool defaults to a dry run. Called without confirm, it describes exactly what would happen and sends nothing to the printer. Pass confirm=true to actually act.

octoprint_start_print(path="cup.gcode")              → 🟡 dry run: "this would start printing cup.gcode"
octoprint_start_print(path="cup.gcode", confirm=true) → 🟢 starts the print

[!NOTE] Read-only tools (octoprint_get_status, octoprint_list_files, octoprint_get_job) never need confirm. Temperatures are also sanity-checked (e.g. the bed is capped at ~140 °C) so a typo can't command a wild value.

---

🧰 Tool reference

All tools accept response_format (markdown or json). Tools marked 🔒 physically actuate the printer and require confirm=true; without it they return a harmless dry-run preview.

Level 1 · Source — Thingiverse

| Tool | What it does | |------|--------------| | thingiverse_search_models | Keyword search for printable "things"; returns candidates with IDs. | | thingiverse_get_model | Details for one thing: license, description, and downloadable files. | | thingiverse_download_model | Download a thing's files (printable models by default) to local disk. |

Level 2 · Slice — Cura or OrcaSlicer

PrintMCP ships two interchangeable slicer backends; use whichever you have installed. Both are auto-detected.

| Tool | What it does | |------|--------------| | cura_slice_model | Slice a local .stl/.obj/.3mf/.amf/.ply into G-code via CuraEngine. Choose printer, layer height, infill, supports, adhesion, and temperatures; returns the G-code path plus estimated print time and filament. | | orca_slice_model | Slice a local model into G-code via OrcaSlicer's CLI using its 3-tier presets (machine + process + filament). Works with native or Flatpak installs. Returns the G-code path plus estimated print time and filament. | | orca_list_profiles | List available OrcaSlicer presets by tier (machine/process/filament), with an optional name filter — use it to find the exact preset names orca_slice_model needs. |

Level 3 · Print — OctoPrint

| Tool | What it does | | |------|--------------|:--:| | octoprint_get_status | Connection state, printer state, and live tool/bed temperatures. | 👁️ | | octoprint_list_files | List G-code files on the server, with their server-side paths. | 👁️ | | octoprint_get_job | Active job: file, % complete, elapsed, and estimated time remaining. | 👁️ | | octoprint_connect | Open or close the printer's serial connection. | 🔒 | | octoprint_upload_file | Upload a local .gcode to the server (optionally select/print). | 🔒¹ | | octoprint_start_print | Select a server-side file and begin printing. | 🔒 | | octoprint_control_job | Pause, resume, or cancel the running job. | 🔒 | | octoprint_set_temperature | Set a tool (nozzle) or bed target temperature. | 🔒 | | octoprint_home | Home one or more axes. | 🔒 | | octoprint_move | Jog the print head by a relative offset. | 🔒 |

_{👁️ read-only · 🔒 requires confirm=true · ¹ uploading alone is safe; only starting a print needs confirm.}

---

📦 Requirements

| | Needed for | Notes | |---|---|---| | Python ≥ 3.10 | everything | — | | uv | everything | Project & dependency manager. | | Thingiverse API token | Level 1 | Free — register an app. | | Ultimaker Cura | Level 2 (Cura) | Its bundled CuraEngine is auto-detected on Windows. | | OrcaSlicer | Level 2 (Orca) | Native or Flatpak; CLI and presets are auto-detected. Either slicer satisfies Level 2. | | An OctoPrint server + API key | Level 3 | Any printer running OctoPrint on your network. |

[!TIP] The levels are independent. You can use Level 1 with just a Thingiverse token, add Cura later for slicing, and wire up OctoPrint whenever your printer is ready.

---

🚀 Quick start

Install from PyPI

uv tool install printmcp      # or:  pipx install printmcp

This puts a printmcp command on your PATH. You can also run it without installing:

uvx printmcp

Install from source

git clone https://github.com/SourceBox-LLC/PrintMCP
cd PrintMCP
uv sync                       # creates .venv, installs PrintMCP + dev tools

Then: configure and run

# Configure your secrets (in the working directory you'll run from)
cp .env.example .env          # Windows: copy .env.example .env
#   …then edit .env (see Configuration below)

# Run the server (stdio — it blocks waiting for an MCP client; that's expected)
printmcp                      # if installed; from source: uv run printmcp

You normally won't run the server by hand — you register it with a client, which launches it for you.

---

⚙️ Configuration

PrintMCP reads configuration from environment variables. A .env file in the project root is loaded automatically (and is git-ignored, so your secrets stay local).

| Variable | Required | Default | Purpose | |----------|:--------:|---------|---------| | THINGIVERSE_TOKEN | Level 1 | — | Thingiverse REST API App Token. | | PRINTMCP_DOWNLOAD_DIR | — | OS Downloads folder (e.g. %USERPROFILE%\Downloads, ~/Downloads); falls back to ~/PrintMCP/downloads if not found | Where downloaded models are saved. | | PRINTMCP_CURA_DIR | — | auto-detected | Ultimaker Cura install folder (e.g. C:\Program Files\UltiMaker Cura 5.11.0). Set only if auto-detection fails. | | PRINTMCP_CURAENGINE | — | <cura>/CuraEngine.exe | Full path to the CuraEngine executable, if it lives outside the Cura folder. | | PRINTMCP_ORCA_COMMAND | — | auto-detected | OrcaSlicer launch command, e.g. orca-slicer or flatpak run com.orcaslicer.OrcaSlicer. Set only if auto-detection fails. | | PRINTMCP_ORCA_PROFILES | — | auto-detected | OrcaSlicer's bundled .../share/OrcaSlicer/profiles directory (the vendor folders of machine/process/filament presets). | | OCTOPRINT_URL | Level 3 | — | Base URL of your OctoPrint server, e.g. http://octopi.local or http://192.168.1.50:80. | | OCTOPRINT_API_KEY | Level 3 | — | Oc