prusactl

<h1 align="center">prusactl</h1>

<p align="center">
  <b>Hand your Prusa 3D printer to an AI agent.</b><br>
  An <a href="https://modelcontextprotocol.io">MCP</a> server that talks to the printer directly on your network, and through <a href="https://connect.prusa3d.com">Prusa Connect</a> from anywhere, with a small CLI to set it up and check on it.
</p>

<p align="center">
  <a href="https://github.com/trevin-lee/prusactl/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/trevin-lee/prusactl/actions/workflows/ci.yml/badge.svg"></a>
  <img alt="Go version" src="https://img.shields.io/github/go-mod/go-version/trevin-lee/prusactl">
  <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-8A2BE2">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

---

`prusactl mcp` gives an agent such as Claude hands on your printer. It can:

- **Watch:** check state, temperatures, job progress, and (with Connect) the camera.
- **Print:** upload files, start them, pause, resume, and stop, and (with Connect)
  queue them.
- **Control:** heat, home, move, load and unload filament, and level the bed:
  through Connect at any time, or as G-code while the printer is idle.
- **Answer the printer:** press the buttons on dialogs shown on its screen, such as
  runout or errors. Needs Connect.
- **Run G-code:** any G-code, over the direct connection, while the printer is idle.

It is one Go binary, and signing in needs no browser: setup is two terminal
prompts. (Deleting files from Prusa Connect's cloud storage is the one thing
that still needs the Connect web app.)

## Things you can ask

> How's the print going? Show me the camera.
>
> Print `~/Downloads/bracket.bgcode`.
>
> Preheat for PETG.
>
> Object 3 is spaghetti. Cancel just that one.
>
> The printer is showing a dialog. What does it say?
>
> What did I print this week, and how many failed?

The camera, cancelling one object, reading a dialog, and print history go
through Prusa Connect, so those need `prusactl login`; the rest works directly.

## Install

**Homebrew** (macOS and Linux):

```sh
brew install trevin-lee/tap/prusactl
```

This builds prusactl from source, so Homebrew installs Go first if you don't
have it; the build itself takes seconds. Tab completion for bash, zsh, and fish
comes with it. Update with `brew upgrade prusactl`. To remove it, see
[Uninstall](#uninstall).

> Installed prusactl 0.1.3 or earlier? That was a cask. Switch once with
> `brew uninstall --cask prusactl && brew update && brew install trevin-lee/tap/prusactl`.
> Your saved printer and Prusa Connect session are kept.

**A downloaded binary:** get the archive for your system from
[Releases](https://github.com/trevin-lee/prusactl/releases): macOS (universal),
Linux (x86-64, ARM64, ARMv7 such as a Raspberry Pi), or Windows (x86-64, ARM64).
`checksums.txt` lists their SHA-256 sums.

```sh
tar -xzf prusactl_*_linux_arm64.tar.gz   # macOS and Linux: unpack the one you downloaded
sudo install prusactl /usr/local/bin/    # or any other folder on your PATH
```

On Windows, unzip it and put `prusactl.exe` in a folder on your `PATH`. The
binaries aren't code-signed: if macOS won't open it because it can't verify the
developer, run `xattr -d com.apple.quarantine /usr/local/bin/prusactl`. To
update, replace the file with a newer release. `prusactl help completion`
shows how to add Tab completion.

**Go:**

```sh
go install github.com/trevin-lee/prusactl/cmd/prusactl@latest
```

This puts it in `$(go env GOPATH)/bin`, which needs to be on your `PATH`. It
needs Go 1.26.6 or newer; recent Go versions fetch that on their own.

Check it worked with `prusactl --version`.

### Uninstall

First remove what prusactl saved: `prusactl setup --forget` deletes the
printer's address and password, and `prusactl logout` deletes the Prusa Connect
session. Then remove the program with `brew uninstall prusactl`, or by deleting
the file. All that's left is a `prusactl` folder holding an empty lock file, in
your config directory (`~/Library/Application Support` on macOS, `~/.config` on
Linux, `%AppData%` on Windows); delete it too if you like.

## Quick start

```sh
prusactl setup 192.168.1.50    # the printer's address; asks for its PrusaLink password
prusactl status

prusactl login                 # optional: Prusa Connect, for remote access, camera, dialogs
```

The PrusaLink password is on the printer under **Settings → Network → PrusaLink**.
PrusaLink is on by default; if someone turned it off, turn it back on there.

`setup` saves one printer for the direct route; running it again for another
printer replaces the first (it says so). With several printers, set up the one
you use most and reach the others through Prusa Connect.

## Connect an AI agent

**Claude Code:**

```sh
claude mcp add --scope user prusa -- "$(command -v prusactl)" mcp
```

`$(command -v prusactl)` saves the full path, so it works even when the app isn't
started from a terminal that has your `PATH`.

**Any other MCP client:** add prusactl as a stdio server, using the path that
`command -v prusactl` prints (`where prusactl` on Windows):

```json
{
  "mcpServers": {
    "prusa": { "command": "/opt/homebrew/bin/prusactl", "args": ["mcp"] }
  }
}
```

**The MCP bundle:** each release includes `prusactl.mcpb`, which carries its own
copy of prusactl for macOS, Linux x86-64, and Windows x86-64. Open it in an app
that installs MCPB extensions, such as Claude Desktop (double-click the file),
and enter the printer's address and PrusaLink password when asked. The bundle
covers the direct route; Prusa Connect sign-in still needs `prusactl login` from
an installed copy.

prusactl is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.trevin-lee/prusactl`, for clients that browse it.

## How it works

```mermaid
flowchart LR
    agent["AI agent<br/>(Claude Code, …)"] -- "MCP over stdio" --> px["prusactl"]
    you["You, in a terminal"] --> px
    px -- "local network<br/>PrusaLink API" --> printer["Your printer"]
    px -. "internet, optional" .-> connect["Prusa Connect"]
    connect <-.-> printer
    px --- keychain[("OS keychain")]
```

prusactl reaches the printer two ways, and each tool picks one:

| | Direct (PrusaLink) | Prusa Connect |
|---|---|---|
| Set up with | `prusactl setup` and the password on the printer's screen | `prusactl login` with your Prusa Account |
| Reaches the printer | On your network | From anywhere |
| Status, files, upload, print, pause/resume/stop | ✅ | ✅ |
| Heat, move, filament, leveling | ✅ via `run_gcode` (printer idle) | ✅ via firmware commands |
| Any G-code | ✅ | ❌ |
| Camera, on-screen dialogs, queue, history, events | ❌ | ✅ |

The direct route is used whenever the printer answers. Otherwise, or for
Connect-only features, the tool goes through Connect. Results from tools that
can take either route say which one they used (`via`); the rest always use the
route their feature needs.

### Signing in to Prusa Connect

`prusactl login` asks for your Prusa Account email and password, plus a 2FA
code if your account has one. It fills in Prusa's own login page over HTTPS the
same way a browser would. It then trades the resulting code for tokens, using
the OAuth + PKCE flow of the Connect web app.

- **Your password** is sent only to account.prusa3d.com and is never stored.
- **Where tokens are kept:** the OS keychain (macOS Keychain, Secret Service, or
  Windows Credential Manager), under the service `prusactl`. A machine without
  one, such as a headless Raspberry Pi, gets `secrets.json` in prusactl's config
  directory instead, readable only by you; `PRUSACTL_KEYRING=file` forces that.
- **Staying signed in:** tokens refresh on their own. Prusa rotates refresh
  tokens, so refreshes are coordinated between processes. Several agents can
  share one session without signing each other out.
- **Google or Apple sign-in** accounts need a Prusa Account password set before
  this works.

The printer's PrusaLink password is kept in the same keychain.

## MCP tools

| Tool | Route | What it does |
| --- | --- | --- |
| `connection_status` | both | How the printer can be reached right now, and what to set up |
| `list_printers`, `get_printer` | both | State, temperatures, job progress, and (via Connect) any dialog on screen |
| `list_printer_files`, `delete_printer_files` | both | Browse or clean up the printer's storage |
| `download_printer_file` | direct | Copy a file from the printer to this computer, e.g. to check the slicer settings a print used |
| `upload_file` | both | Send a local `.bgcode`/`.gcode` to the printer, and optionally start or queue it |
| `start_print` | both | Print a file already on the printer |
| `control_print` | both | Pause, resume, or stop |
| `get_transfers` | both | File transfers in progress |
| `run_gcode` | direct | Run G-code, such as heating, homing, moving, or filament changes, while the printer is idle |
| `get_camera_snapshot` | Connect | Latest camera image, with how old it is |
| `respond_to_dialog` | Connect | Press a button on the printer's screen |
| `list_supported_commands`, `send_command`, `get_command` | Connect | Every firmware command Connect exposes, with arguments and allowed states |
| `get_queue`, `add_to_queue`, `remove_from_queue` | Connect | The print queue |
| `list_jobs`, `get_job` | Connect | Print history, and the objects in a job that can be cancelled |
| `get_telemetry`, `list_events` | Connect | Telemetry history and the event log |
| `list_connect_files` | Connect | Connect cloud storage |
| `api_request` | both | Any other endpoint: `/api/...` goes to the printer, `/app/...` to Connect |

Every `printer` argument accepts a name, serial number, or Connect UUID. With one
printer you can leave it out. `via: "direct"` or `via: "connect"` forces a route.

## CLI

```text
prusactl setup [ADDRESS]           connect directly to the printer on your network
prusactl lo