Skip to content

getting-started.md

Latest commit

 

History

History
197 lines (138 loc) · 5.98 KB

getting-started.md

File metadata and controls

197 lines (138 loc) · 5.98 KB
Raw

🚀 Getting Started

This guide takes you from a fresh clone to a running PrintMCP server connected to your AI assistant. Budget about 10 minutes.

New here? PrintMCP is an MCP server. You don't run it like a normal app — an MCP client (Claude Desktop, Claude Code, etc.) launches it and talks to it over stdin/stdout. This guide ends with registering it in a client.

1. Prerequisites

Tool Why Check
Python ≥ 3.10 Runtime python --version
uv (recommended) Installs & runs PrintMCP (or use pipx) uv --version
A Thingiverse token Level 1 (search/download) Get one below
Ultimaker Cura (optional) Level 2 (slicing) Only if you'll slice
OctoPrint + API key (optional) Level 3 (printing) Only if you'll print

Tip

The three levels are independent. You can finish this guide with only a Thingiverse token and start searching/downloading immediately — add Cura and OctoPrint later.

If you don't have uv yet:

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install

From PyPI (puts a printmcp command on your PATH):

uv tool install printmcp      # or:  pipx install printmcp

From source (for development, or to get the latest unreleased code):

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

Verify the install and see what's configured:

printmcp --check              # from source: uv run printmcp --check

This reports the setup status of each level (it never prints your secrets). Right after install it'll show everything as missing — that's expected; you'll configure credentials next. Other handy commands: printmcp --version and printmcp --help.

3. Configure your credentials

PrintMCP reads configuration from environment variables, loaded automatically from a .env file in the project root. Copy the template:

cp .env.example .env     # Windows: copy .env.example .env

Then fill in what you need. For the full list, see Configuration.

Thingiverse token (Level 1 — required to search/download)

  1. Go to https://www.thingiverse.com/apps/create and register an app (the free "Desktop/Web" type is fine).

  2. Copy its App Token.

  3. Put it in .env:

    THINGIVERSE_TOKEN=your-app-token-here

OctoPrint (Level 3 — only if you'll print)

OCTOPRINT_URL=http://octopi.local      # or http://<printer-ip>:<port>
OCTOPRINT_API_KEY=your-octoprint-api-key

Get the key from OctoPrint → Settings → API (global key), or a per-user Application Key. See Configuration for details.

Warning

.env holds secrets. It's already git-ignored — never commit it. Only .env.example (with empty values) belongs in the repo.

Cura (Level 2 — usually automatic)

Nothing to configure if Cura is installed in the standard location — PrintMCP auto-detects it.

Tip

Downloaded models are saved to your OS Downloads folder by default (~/Downloads on macOS/Linux, %USERPROFILE%\Downloads on Windows). Set PRINTMCP_DOWNLOAD_DIR in .env to use a custom location. Only set PRINTMCP_CURA_DIR if auto-detection fails. See Configuration.

4. Confirm your configuration

Re-run the check now that you've set up .env — the levels you configured should switch to OK:

printmcp --check              # or:  uvx printmcp --check  /  uv run printmcp --check (from a clone)

You can also start the server directly as a sanity check:

uvx printmcp                  # from a clone:  uv run printmcp

It will block silently, waiting for an MCP client on stdin/stdout. That's correct behavior — press Ctrl+C to stop. Normally you don't run it by hand; the client does.

5. Register with an MCP client

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

# macOS / Linux
./scripts/setup-mcp.sh
# Windows (PowerShell)
.\scripts\setup-mcp.ps1

Important

Quit the client before running it. MCP clients rewrite their config when they close, so a setup applied while the client is open would be lost. If your chosen client is running, the script stops and asks you to close it and re-run. Details in scripts/README.md.

Prefer to do it by hand? Add PrintMCP to your client's MCP config. Most users want the published package (uvx printmcp) — no clone needed:

Claude Desktop / Cursor / Windsurf

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

Claude Code CLI

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

Restart the client. PrintMCP's tools will appear in the tool list.

Working on PrintMCP (contributors)? Point the client at your clone so edits take effect immediately: "command": "uv", "args": ["run", "--directory", "/path/to/PrintMCP", "printmcp"].

6. Your first print

Setup's done — from here on, you just talk to your assistant. Head to Tutorial 1 · Find Something to Print and find your first model by simply asking for it.

Troubleshooting

Hitting an error? The Troubleshooting guide covers the common ones — like THINGIVERSE_TOKEN is not set, Cura not being found, or the printer being unreachable.