printmcp 0.3.0

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.

🧭 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"])

📑 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/.

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

Level 2 · Slice — Cura or OrcaSlicer

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

Level 3 · Print — OctoPrint

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

📦 Requirements

[!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).

🔌 Register with an MCP client

PrintMCP runs as a stdio server any MCP client can launch. PrintPal is one such client; you can also point your own agent — Claude Code, Claude Desktop, Cursor, Windsurf, opencode — at it directly.

Automatic

The setup script detects your installed MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, opencode), lets you pick one, and configures it for you. By default it registers the published package (uvx printmcp); pass --directory <path> / -Directory <path> to register a local checkout instead.

# macOS / Linux — run from anywhere
curl -fsSL https://raw.githubusercontent.com/SourceBox-LLC/PrintMCP/master/scripts/setup-mcp.sh | bash
# or, from a clone:  ./scripts/setup-mcp.sh

# Windows (PowerShell) — from a clone
.\scripts\setup-mcp.ps1

[!IMPORTANT] Close the client first. MCP clients rewrite their config when they exit, so a setup that runs while the client is open gets clobbered. If the client you choose is running, the script tells you to quit it and run again. See scripts/README.md.

Manual

Add the server to your client's MCP config. Most users want the published package (uvx printmcp) — no clone needed:

{
  "mcpServers": {
    "printmcp": {
      "command": "uvx",
      "args": ["printmcp"]
    }
  }
}

claude mcp add --scope user --transport stdio printmcp -- uvx printmcp

{
  "mcp": {
    "printmcp": {
      "type": "local",
      "command": ["uvx", "printmcp"],
      "enabled": true
    }
  }
}

Working on PrintMCP itself? Use a local checkout

Contributors developing PrintMCP alongside its clients should point the client at their clone (so edits take effect immediately) instead of the published package:

{
  "mcpServers": {
    "printmcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/PrintMCP", "printmcp"]
    }
  }
}

💡 Example: coffee cup to print

You don't call tools — you just talk to your assistant, and it drives the whole pipeline. A full run sounds like this:

💬 You: "I want to 3D print a coffee cup. Find one, get it ready for my Ender 3, and start it."

🤖 Assistant: "I found a few coffee cups on Thingiverse — here are the top three…"

💬 You: "The first one."

🤖 Assistant: "Good pick — it's licensed Creative Commons (free to print). I've downloaded and sliced it for your Ender-3 Pro: about 6h 31m and ~25.5 m of filament. Before I start the physical printer — ready for me to begin?"

💬 You: "Yes, go."

🤖 Assistant: "Printing now! 🎉 Ask me any time for progress."

💬 You: (later) "How's it going?"

🤖 Assistant: "About 42% done — roughly 2h 14m left."

One request, one finished cup. The assistant handles the busywork (searching, downloading, slicing, uploading); you make the decisions that matter — which model, and the go-ahead to start.

[!NOTE] Anything that touches the physical printer — heating, moving, starting a print — pauses for your confirmation first. Everything up to slicing is purely local and needs no go-ahead. See the Safety Model.

Want the step-by-step version? The tutorials walk through it in plain conversation.

🗂️ Project structure

PrintMCP/
├── src/printmcp/
│   ├── app.py          # shared FastMCP instance
│   ├── server.py       # entry point — registers tools, runs over stdio
│   ├── config.py       # env-driven config (tokens, Cura + OrcaSlicer paths, OctoPrint URL/key)
│   ├── thingiverse.py  # Level 1 — search & download
│   ├── cura.py         # Level 2 — slice via CuraEngine
│   ├── orca.py         # Level 2 — list presets & slice via OrcaSlicer CLI
│   └── octoprint.py    # Level 3 — print management
├── docs/                # full documentation (guides, tool reference, tutorials)
│   ├── README.md        # documentation hub
│   ├── getting-started.md, configuration.md, safety.md, troubleshooting.md, architecture.md
│   ├── tools/           # per-level tool reference
│   └── tutorials/       # step-by-step walkthroughs
├── tests/               # offline tests (validation + mock-transport HTTP)
├── .env.example
├── pyproject.toml
└── README.md

🧪 Development

uv run pytest                       # tests
uvx ruff check src tests            # lint
uvx ruff format --check src tests   # formatting

CI runs all three on every push and PR (tests across Python 3.10–3.13).

The suite is fully offline — it requires no token, network, or Cura install and runs in under two seconds. It covers:

• Input validation & helpers — tool registration, filename sanitization, slice-input ranges, stats parsing.
• The Level 3 safety gate — every actuating tool refuses to act (and sends nothing) without confirm=true.
• OctoPrint HTTP plumbing — using a mock transport, it asserts the exact method, path, JSON body, and X-Api-Key header of every request, that responses parse correctly, and that error statuses (401/409/ connection-refused) map to friendly messages — all without a printer.
• OrcaSlicer plumbing (test_orca.py) — preset name resolution across vendor dirs and the global library, scalar override application, per-OS binary/profile discovery (monkeypatched), flatpak --filesystem grant ordering in the launch argv, and G-code footer stats parsing — all offline against a synthetic profiles tree.
• The real stdio transport (test_stdio.py) — spawns python -m printmcp as a subprocess, speaks the MCP JSON-RPC protocol over stdio with the official client, and round-trips a tool call. Catches startup/registration failures and any accidental stdout writes that would corrupt the stream — without network or a printer.

Developing with PrintPal

PrintPal (the terminal UI) launches PrintMCP as a subprocess. To have PrintPal use your local PrintMCP checkout instead of the PyPI release while you edit tools, set PRINTPAL_PRINTMCP_COMMAND before starting it:

export PRINTPAL_PRINTMCP_COMMAND="uv run --directory /path/to/PrintMCP printmcp"
# then, from your PrintPal checkout:  uv run printpal

PrintPal's banner shows which server it connected to. See the PrintPal README for details.

Notable changes are tracked in CHANGELOG.md; releasing is documented in docs/RELEASING.md.

🗺️ Roadmap

• More print backends — a Moonraker/Klipper backend exposing moonraker_* tools alongside the OctoPrint ones, so non-OctoPrint printers work too.
• Slicing depth — more printer profiles and quality presets, and surfacing CuraEngine warnings (e.g. a model larger than the build volume).
• More model sources — Printables, MyMiniFactory, and others behind a shared search interface.

⚖️ Model licensing

Models on Thingiverse carry their own licenses (often Creative Commons; some are non-commercial). thingiverse_get_model and thingiverse_download_model surface each model's license — respect it before reusing, remixing, or selling a print.

📄 License

Licensed under the Apache License 2.0 — © 2026 SourceBox LLC.

You may freely use, modify, and distribute this software, including for commercial purposes, provided you retain the copyright and license notices and state any significant changes. The license also includes an express patent grant. It comes with no warranty. See the LICENSE file for the full text.

[!NOTE] This license covers PrintMCP's own code only. Third-party tools it drives (Ultimaker Cura, OctoPrint) and any 3D models you download carry their own licenses — see Model licensing above.