printmcp 0.1.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"]
        direction TB
        SL["cura_slice_model"]
    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. Drives the same CuraEngine that Ultimaker Cura ships, and reports 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

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

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:

# Windows (PowerShell)
.\scripts\setup-mcp.ps1

# macOS / Linux
./scripts/setup-mcp.sh

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

{
  "mcpServers": {
    "printmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\Sbuss\\Documents\\Software Development\\Projects\\PrintMCP",
        "printmcp"
      ]
    }
  }
}

claude mcp add printmcp -- uv run --directory "C:\Users\Sbuss\Documents\Software Development\Projects\PrintMCP" printmcp

[!TIP] Point --directory at wherever you cloned PrintMCP. The client launches the server and talks to it over stdio.

💡 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 paths, OctoPrint URL/key)
│   ├── thingiverse.py  # Level 1 — search & download
│   ├── cura.py         # Level 2 — slice via CuraEngine
│   └── 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.

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.