prusactl

prusactl

将 Prusa 3D 打印机交给 AI Agent。
一个MCP 服务，可直接通过网络与打印机通信，也可通过 Prusa Connect 随时随地连接；另有一个 CLI，能完成 Agent 所能做的一切。

---

prusactl mcp 能让 Claude 这样的 Agent 直接操作你的打印机。它可以：

• **查看：**检查状态、温度、打印进度和摄像头画面（通过 setup --camera 使用 RTSP，或通过 Connect 查看）。
• **打印：**上传文件、开始打印、暂停、恢复和停止；（使用 Connect 时）还可将任务加入队列。
• **控制：**加热、归零、移动、装入和卸下耗材，以及调平热床： 随时通过 Connect 操作，或在打印机空闲时发送 G-code。
• **响应打印机：**按下屏幕对话框中的按钮，例如耗材用尽或错误提示。需要 Connect。
• **运行 G-code：**在打印机空闲时，通过直接连接运行任意 G-code。

它是一个 Go 二进制文件；无需浏览器。只需在终端中回答两个提示即可完成设置。

你可以这样提问

打印进展如何？给我看看摄像头画面。

打印 ~/Downloads/bracket.bgcode。

为 PETG 预热。

对象 3 打印得一团糟。只取消这个对象。

打印机上显示了一个对话框。上面写了什么？

我这周打印了什么？有多少次失败？

取消单个对象、读取对话框和查看打印历史都需要通过 Prusa Connect，因此需要先运行 prusactl login；其他功能可直接使用。摄像头也可以直接使用，但需要先告诉 prusactl 摄像头的位置（见摄像头）。

安装

Homebrew（macOS 和 Linux）：

brew install trevin-lee/tap/prusactl

这会从源代码构建 prusactl，因此如果你尚未安装 Go，Homebrew 会先安装 Go；构建本身只需几秒钟。安装后即可使用 bash、zsh 和 fish 的 Tab 补全。使用 brew upgrade prusactl 更新。卸载方法请参见卸载。

安装的是 0.1.3 或更早版本的 prusactl？那时它是一个 cask。运行 brew uninstall --cask prusactl && brew update && brew install trevin-lee/tap/prusactl 一次性切换。 已保存的打印机和 Prusa Connect 会话都会保留。

**下载的二进制文件：**从 Releases 下载适用于你系统的压缩包：macOS（通用版）、 Linux（x86-64、ARM64、ARMv7，例如 Raspberry Pi）或 Windows（x86-64、ARM64）。 checksums.txt 列出了这些文件的 SHA-256 校验和。

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

在 Windows 上，解压文件并将 prusactl.exe 放入 PATH 中的文件夹。二进制文件未经代码签名：如果 macOS 因无法验证开发者而拒绝打开，请运行 xattr -d com.apple.quarantine /usr/local/bin/prusactl。更新时，用较新版本替换该文件。运行 prusactl help completion 可查看如何启用 Tab 补全。

Go：

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

程序会安装到 $(go env GOPATH)/bin，该目录需要位于 PATH 中。需要 Go 1.26.6 或更高版本；较新的 Go 版本会自动下载所需版本。

运行 prusactl --version 检查是否安装成功。

卸载

先删除 prusactl 保存的内容：prusactl setup --forget 会删除打印机地址和密码，prusactl logout 会删除 Prusa Connect 会话。然后使用 brew uninstall prusactl 卸载程序，或者直接删除文件。最后只剩下一个 prusactl 文件夹，其中有一个空锁文件，位于你的配置目录中（macOS 上是 ~/Library/Application Support，Linux 上是 ~/.config，Windows 上是 %AppData%）；如有需要，也可以将其删除。

快速开始

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

prusactl setup --camera rtsp://192.168.1.60/live   # optional: the camera, no Connect needed
prusactl login                 # optional: Prusa Connect, for remote access, camera, dialogs

PrusaLink 密码可在打印机上通过 设置 → 网络 → PrusaLink 查看。 PrusaLink 默认处于开启状态；如果有人将其关闭，请在此处重新开启。

setup 会为直接连接方式保存一台打印机；如果对另一台打印机再次运行， 第一台打印机会被替换（命令会说明这一点）。如果有多台打印机，请设置最常用的那台， 其他打印机则通过 Prusa Connect 访问。

连接 AI Agent

Claude Code：

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

$(command -v prusactl) 会保存完整路径，因此即使应用不是从包含 PATH 的终端启动，也能正常工作。

其他 MCP 客户端： 将 prusactl 添加为 stdio 服务，并使用 command -v prusactl 输出的路径（Windows 上使用 where prusactl）：

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

MCP 捆绑包： 每个版本都包含 prusactl.mcpb，其中为 macOS、Linux x86-64 和 Windows x86-64 附带了 prusactl 副本。用支持安装 MCPB 扩展的应用打开该文件，例如 Claude Desktop（双击文件）， 并在提示时输入打印机地址和 PrusaLink 密码。该捆绑包支持直接连接方式；登录 Prusa Connect 仍需从 已安装的副本运行 prusactl login。

prusactl 也已列入 MCP Registry，名称为 io.github.trevin-lee/prusactl，供支持浏览该目录的客户端使用。

Claude Code 技能： skills/prusactl/SKILL.md 会向 Agent 传授工作流（检查状态、查看打印板后开始打印、监控故障、更新固件）以及相关风险。将该文件夹复制到 ~/.claude/skills/prusactl/（或项目的 .claude/skills/）即可使用。

工作原理

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 通过两种方式连接打印机，每个工具会选择其中一种：

	直接连接（PrusaLink）	Prusa Connect
设置方式	使用 prusactl setup 和打印机屏幕上显示的密码	使用 Prusa Account 运行 prusactl login
连接打印机	在你的网络上	从任何地方
状态、文件、上传、打印、暂停/恢复/停止	✅	✅
加热、移动、耗材、调平	✅ 通过 run_gcode（打印机空闲时）	✅ 通过固件命令
任意 G-code	✅	❌
摄像头	✅ 通过 RTSP 和 ffmpeg，保存其地址后即可使用	✅
屏幕对话框、队列、历史记录、事件	❌	✅

只要打印机有响应，就会使用直接连接方式。否则，或者需要使用仅支持 Connect 的功能时，工具会通过 Connect 连接。可以使用任一连接方式的工具会在结果中说明使用了哪种方式（via）；其他工具则始终使用其功能所需的连接方式。

摄像头

Buddy3D 摄像头不是打印机的一部分，而是一个独立的 Wi-Fi 设备，会自行与 Prusa Connect 通信，并通过 rtsp://<camera-ip>/live 提供视频流；打印机的 PrusaLink 没有摄像头端点（Buddy 固件不提供），因此仅直接连接无法显示画面。告知 prusactl 摄像头地址后，它会使用 ffmpeg 每次抓取一帧；ffmpeg 必须位于你的 PATH 中：

prusactl setup --camera rtsp://192.168.1.60/live   # find the camera's IP in your router
prusactl camera snapshot.jpg

快照来自第一个可用来源：打印机自身的 /api/v1/cameras/snap（如果其 PrusaLink 提供该端点；其他 PrusaLink 版本有此功能）；已保存的 RTSP 地址；然后是 Prusa Connect。via: "direct" 会将来源限制为前两项，via: "connect" 则限制为 Connect。PRUSACTL_CAMERA_URL 会覆盖已保存的地址。包含用户名或密码的地址会被拒绝：ffmpeg 会在命令行中接收密码，任何本地用户都能通过 ps 读取；而且密码还会以明文形式保存在配置中。Buddy3D 摄像头无需用户名或密码。

只接受纯 rtsp:// 地址。出于安全考虑，会拒绝 rtsps://：即使使用 -tls_verify 1 和 -ca_file，FFmpeg 7.1.5 仍会使用自签名证书完成 TLS 握手并发送摄像头凭据，因为其 RTSP 代码从未将这些选项传递给 TLS 层。Buddy3D 摄像头提供纯 RTSP，因此不会因此损失任何功能。剩余风险：纯 RTSP 会以未加密的方式传输视频，因此网络上的任何人都能观看；请勿将摄像头连接到不可信的网络。

登录 Prusa Connect

prusactl login 会要求你输入 Prusa Account 邮箱和密码，如果你的账户启用了双重身份验证，还会要求输入 2FA 验证码。它会像浏览器一样，通过 HTTPS 填写 Prusa 自己的登录页面。然后，它会使用 Connect Web 应用的 OAuth + PKCE 流程，将获得的代码换成令牌。

让 AI Agent 代你登录。 prusactl login --manual 不会接触密码。它会单独打印一行 Prusa Account 链接（除非你传入 --no-open，否则还会在浏览器中打开该链接），然后从 stdin 读取一行内容：浏览器在你批准后最终停留的地址，其格式类似 https://connect.prusa3d.com/login/auth-callback?code=...&state=...（单独的 code= 值也可以）。Agent 可以代为操作；skills/prusactl/SKILL.md 说明了具体方法。没有本地回环模式：Prusa Account 会拒绝 Connect 客户端使用 127.0.0.1 重定向（“Mismatching redirect URI”），因此只能从地址栏读取代码。此流程还依赖 Connect 的 auth-callback 页面在 state 不是由该页面签发时仍保留代码，而目前页面正是这样处理的。如果 Prusa 更改了这一行为，登录会在令牌步骤失败，需要更新 prusactl。

• 你的密码只会发送到 account.prusa3d.com，绝不会被存储。
• **令牌的保存位置：**操作系统密钥链（macOS Keychain、Secret Service 或 Windows Credential Manager），服务名为 prusactl。没有密钥链的设备（例如无头 Raspberry Pi）会将令牌保存在 prusactl 配置目录中的 secrets.json，且只有你能读取；设置 PRUSACTL_KEYRING=file 可强制使用这种方式。
• **保持登录状态：**令牌会自动刷新。Prusa 会轮换刷新令牌，因此多个进程之间的刷新操作会协调进行。多个 Agent 可以共享一个会话，而不会让彼此退出登录。
• 使用 Google 或 Apple 登录的账户必须先设置 Prusa Account 密码才能使用此功能。

打印机的 PrusaLink 密码也保存在同一密钥链中。

MCP 工具

工具	路由	功能
connection_status	both	当前如何连接打印机，以及需要进行哪些设置
list_printers、get_printer	both	状态、温度、作业进度，以及（通过 Connect）屏幕上的任何对话框
list_printer_files、delete_printer_files	both	浏览或清理打印机的存储空间
download_printer_file	direct	将文件从打印机复制到这台电脑，例如检查打印所用的切片设置
upload_file	both	将本地 .bgcode/.gcode 发送到打印机，并可选择立即开始或加入队列
start_print	both	打印打印机上已有的文件
control_print	both	暂停、继续或停止
get_transfers	both	正在进行的文件传输
run_gcode	direct	在打印机空闲时运行 G-code，例如加热、归位、移动或换料
get_camera_snapshot	both	摄像头图像：如果已保存摄像头的 RTSP 流地址，则从该流获取；否则获取 Connect 的最新图像，并显示图像的时间
respond_to_dialog	Connect	按下打印机屏幕上的按钮
list_supported_commands、send_command、get_command	Connect	Connect 提供的所有固件命令，包括参数和允许的状态
get_queue、add_to_queue、remove_from_queue	Connect	打印队列
list_jobs、get_job	Connect	打印历史记录，以及作业中可取消的对象
get_telemetry、list_events	Connect	遥测历史记录和事件日志
list_connect_files	Connect	Connect 云存储
delete_connect_files	Connect	从 Connect 云存储中删除文件，释放团队配额
get_firmware_status	Connect	打印机运行的固件、Connect 提供的最新固件，以及两者是否不同
update_firmware	Connect	将固件复制到打印机的 USB 驱动器，并使用 FLASH 安装（参见固件）
api_request	both	其他任何端点：/api/... 请求发送到打印机，/app/... 请求发送到 Connect

每个 printer 参数都接受名称、序列号或 Connect UUID。只有一台打印机时，可以省略此参数。via: "direct" 或 via: "connect" 可强制指定路由。

命令行界面

prusactl setup [ADDRESS]           connect directly to the printer on your network
prusactl login [--manual]          optional: sign in to Prusa Connect
prusactl logout                    forget the Prusa Connect session
prusactl status                    printer state and how it is reachable
prusactl mcp                       run the MCP server on stdio

prusactl printers                  the printers prusactl can reach
prusactl print FILE                upload a sliced file and start printing it
prusactl start PATH                start a file already on the printer
prusactl pause | resume | stop     control the running print
prusactl gcode "G28" ["M104 S215"] run G-code as a one-off job
prusactl dialog BUTTON             answer a question on the printer's screen
prusactl files ls|get|put|rm       browse and manage files on the printer
prusactl cloud ls|rm               files in Prusa Connect's cloud storage
prusactl queue ls|add|rm           the Prusa Connect print queue
prusactl jobs [JOB-ID]             print history, or one job
prusactl events                    the printer's recent events
prusactl telemetry                 recorded temperatures and speeds
prusactl transfers                 file transfers in progress
prusactl camera [FILE]             save a snapshot from the printer's camera (RTSP or Connect)
prusactl cmd ls|send|status        run a firmware command through Prusa Connect
prusactl firmware [update]         the printer's firmware; update installs the latest via Connect

prusactl api [METHOD] PATH [JSON]  /api/... to the printer, /app/... to Prusa Connect
prusactl completion bash|zsh|fish  print a shell completion script
prusactl help [COMMAND]            the command list, or one command's details
prusactl version                   print the version (--version does the same)

打印机命令通过内存中的连接运行 MCP 服务提供的同一批工具，因此命令行界面和 Agent 会通过相同的代码路径访问打印机，并执行相同的安全检查；两者都无法执行对方做不到的操作。大多数命令都接受 --printer NAME 来选择打印机，并接受 --via direct 或 --via connect 来强制指定路由；prusactl help <command> 会列出每个命令接受的参数。所有命令都接受 --json。

同样适用打印板检查：打印完成或停止后，任何会启动作业的操作都会询问打印板是否已清空。脚本可用 --plate-clear 表示已清空。

prusactl help <command>（或 <command> --help）会说明命令及其标志；标志可放在参数之前或之后。命令、标志及其取值均支持 Tab 补全：通过 Homebrew 安装时会为 bash、zsh 和 fish 配置补全；prusactl help completion 则会说明如何在其他情况下启用补全。

prusactl setup --forget 会移除已保存的打印机和摄像头。--api-key 使用 PrusaLink API 密钥而不是密码；--password-stdin 从管道读取密码；--camera URL 会保存摄像头的 RTSP 地址（单独使用时不会影响打印机；--no-camera 只会移除摄像头配置）。

prusactl api 会在响应中隐藏 API 密钥和令牌（Connect 的打印机记录中包含 PrusaLink 和 Connect 密钥），因此其输出可以安全地粘贴或交给 Agent。--raw 会显示这些密钥和令牌。

固件

prusactl firmware 会显示打印机正在运行的固件，以及 Prusa Connect 为其提供的最新固件。prusactl firmware update 会让 Connect 将其托管的 .bbf 文件复制到打印机的 USB 驱动器，然后通过 FLASH 命令安装，这会重启打印机。它会等待复制完成。如果没有指定 --version，则会依据 Connect 对固件的判断；如果 Connect 没有判断结果，它会拒绝自行决定。

prusactl firmware                       # running vs latest
prusactl firmware update [--version X]  # copy, then install

只有当打印机处于空闲、就绪、已完成或已停止状态时，才会接受 FLASH。如果打印正在进行，它会在复制任何内容之前拒绝执行；请在打印结束后重新运行。是否需要更新由 Prusa Connect 自行判断，因此除非传入 --version，否则绝不会将固件降级到低于 Connect 最新版本的版本。打印机可能会要求你在屏幕上确认。 固件更新只能通过 Prusa Connect 进行，因此你需要运行 prusactl login。

限制

• 它没有实体操作能力。 它无法清理构建板、更换线轴或疏通堵塞。工具描述会告知 Agent 在开始打印或移动任何东西之前检查打印机（以及摄像头，如有）。启动任务的工具遇到忙碌的打印机时会拒绝执行。打印完成或停止后，所有会启动任务或朝构建板移动的操作（start_print、带有 print 的 upload_file、run_gcode，以及 send_command 的 HOME、MOVE、MOVE_Z、MESH_BED_LEVELING 或 START_PRINT）还需要 plate_clear: true，因为打印完成后，构建板上可能仍留有最后一个部件。将打印机标记为就绪也表示同样的确认。api_request 是原始访问方式，会跳过这些检查。
• plate_clear 是 Agent 自行作出的声明。 没有任何方式可以检查构建板是否为空，因此工具描述会告知 Agent 在传入该参数之前，通过摄像头快照或用户确认来核实。删除操作不可撤销；对于看起来不对劲的打印，建议先暂停。
• run_gcode 会像一个微型打印任务那样运行。 因此，它只能在打印机空闲时使用，而且会显示在打印机历史记录中。它还会在打印机上留下文件 /usb/prusactl-macro.gcode，每次运行都会覆盖该文件。
• Connect 的 API 并非官方 API。 Prusa 不会公开此 API；prusactl 使用的端点与 connect.prusa3d.com 相同，因此 Prusa 方面的变更可能会导致 Connect 路由失效。直接路由使用 Prusa 提供的文档化 PrusaLink API。如果任一路由发生变化，prusactl 会明确说明，而不会出现异常行为："Prusa Connect answered in a way this version of prusactl doesn't recognize: …"，并指出请求及意外情况。更新 prusactl 通常可以解决问题；如果最新版本仍无法解决，请将该消息作为问题报告。

配置

变量	用途
PRUSACTL_HOST、PRUSACTL_USER、PRUSACTL_AUTH	覆盖已保存的打印机地址、用户名或 digest/api-key
PRUSACTL_PASSWORD、PRUSACTL_API_KEY	使用打印机密钥，而非系统密钥链
PRUSACTL_KEYRING=file	将凭据保存在 secrets.json（模式 0600）中，而非系统密钥链
PRUSACTL_CAMERA_URL	覆盖已保存摄像头的 RTSP 地址，例如 rtsp://192.168.1.60/live
PRUSACTL_CONFIG	指定备用配置文件（默认：OS 配置目录中的 prusactl/config.json）
PRUSA_CONNECT_URL、PRUSA_ACCOUNT_URL	Connect 和 Prusa Account 的源地址
PRUSA_CLIENT_ID、PRUSA_REDIRECT_URI	OAuth 客户端（默认使用 Connect Web 应用的客户端）

开发

go test ./...
go vet ./...

推送 vX.Y.Z 标签即可发布新版本。CI 会构建二进制文件、更新 Homebrew tap、附加 MCP bundle，并发布到 MCP Registry。请参阅 CHANGELOG.md。

许可证

MIT。

prusactl 是一个独立项目，与 Prusa Research 无关联，也未获得其认可。Prusa 和 Prusa Connect 是 Prusa Research a.s. 的商标。