prusactl

prusactl

Prusa 3DプリンターをAIエージェントに任せましょう。
プリンターとネットワーク経由で直接通信し、どこからでもPrusa Connectを通じて通信できるMCPサーバーと、エージェントができることをすべて実行できるCLIです。

---

prusactl mcpを使うと、Claudeなどのエージェントにプリンターを操作させることができます。次の操作が可能です。

• 監視： 状態、温度、印刷の進行状況、カメラを確認します（RTSP経由で setup --cameraを使うか、Connect経由で確認します）。
• 印刷： ファイルをアップロードして印刷を開始し、一時停止、再開、停止します。また、Connect経由では印刷をキューに追加できます。
• 制御： 加熱、原点復帰、移動、フィラメントのロードとアンロード、ベッドのレベリングを実行します。 Connect経由ならいつでも、またはプリンターがアイドル状態のときにGコードとして実行できます。
• プリンターへの応答： フィラメント切れやエラーなど、画面に表示されたダイアログのボタンを押します。Connectが必要です。
• Gコードの実行： プリンターがアイドル状態のときに、直接接続経由で任意のGコードを実行します。

Goの単一バイナリで、ブラウザーは不要です。セットアップはターミナルでの2つのプロンプトだけで完了します。

できること

印刷の進み具合はどうですか？カメラを見せてください。

~/Downloads/bracket.bgcodeを印刷してください。

PETG用に予熱してください。

オブジェクト3はスパゲッティ状態です。それだけをキャンセルしてください。

プリンターにダイアログが表示されています。何と書いてありますか？

今週は何を印刷しましたか？失敗した印刷はいくつですか？

オブジェクトごとのキャンセル、ダイアログの読み取り、印刷履歴の確認にはPrusa Connectを使うため、prusactl loginが必要です。それ以外は直接動作します。カメラも、 接続先をprusactlに設定すれば使えます（カメラを参照）。

インストール

Homebrew（macOSおよびLinux）：

brew install trevin-lee/tap/prusactl

prusactlはソースからビルドされるため、Goがインストールされていない場合はHomebrewが先にインストールします。ビルド自体は数秒で完了します。bash、zsh、fish用のタブ補完も含まれています。brew upgrade prusactlで更新できます。アンインストール方法については、アンインストールを参照してください。

prusactl 0.1.3以前をインストールしている場合、当時はcaskでした。次のコマンドを一度実行して切り替えてください。 brew uninstall --cask prusactl && brew update && brew install trevin-lee/tap/prusactl。 保存済みのプリンター情報とPrusa Connectのセッションは維持されます。

ダウンロードしたバイナリ： お使いのシステムに対応するアーカイブを リリースから入手してください。macOS（ユニバーサル）、 Linux（x86-64、ARM64、Raspberry PiなどのARMv7）、または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で確認できます。

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を実行するか、ファイルを削除してプログラムをアンインストールします。設定ディレクトリー（macOSでは~/Library/Application Support、Linuxでは~/.config、Windowsでは%AppData%）に、空のロックファイルが入ったprusactlフォルダーだけが残ります。必要であれば、このフォルダーも削除してください。

クイックスタート

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 のパスワードは、プリンターの Settings → Network → PrusaLink にあります。 PrusaLink はデフォルトで有効です。無効にされている場合は、そこで再度有効にしてください。

setup は直接接続用のプリンターを1台保存します。別のプリンターに対して再度実行すると、最初のプリンターが置き換えられます（その旨が表示されます）。複数のプリンターがある場合は、最もよく使うプリンターを設定し、ほかのプリンターには Prusa Connect 経由でアクセスしてください。

AI エージェントを接続する

Claude Code：

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

$(command -v prusactl) はフルパスを保存するため、PATH が設定されたターミナルからアプリを起動していない場合でも動作します。

その他の MCP クライアント： command -v prusactl が出力するパスを使って、prusactl を stdio サーバーとして追加します（Windows では where prusactl を使います）。

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

MCP バンドル： 各リリースには prusactl.mcpb が含まれており、macOS、Linux x86-64、Windows x86-64 用の prusactl が同梱されています。Claude Desktop など、MCPB 拡張機能をインストールできるアプリで開き（ファイルをダブルクリック）、表示されたらプリンターのアドレスと PrusaLink のパスワードを入力してください。このバンドルは直接接続に対応しています。Prusa Connect へのサインインには、インストール済みのコピーから prusactl login を実行する必要があります。

prusactl は MCP Registry にも io.github.trevin-lee/prusactl として登録されており、クライアントから参照できます。

Claude Code 用スキル： skills/prusactl/SKILL.md は、ワークフロー（状態の確認、プレートを確認してからの印刷開始、失敗の監視、ファームウェアの更新）と注意事項をエージェントに教えます。使用するには、フォルダーを ~/.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 は2つの方法でプリンターにアクセスし、各ツールはいずれかを選択します。

	直接接続（PrusaLink）	Prusa Connect
セットアップ方法	prusactl setup とプリンター画面に表示されるパスワード	Prusa アカウントで prusactl login
プリンターへのアクセス	ネットワーク上	どこからでも
状態、ファイル、アップロード、印刷、一時停止／再開／停止	✅	✅
加熱、移動、フィラメント、レベリング	✅ run_gcode 経由（プリンターがアイドル状態の場合）	✅ ファームウェアコマンド経由
任意の G-code	✅	❌
カメラ	✅ RTSP と ffmpeg 経由。アドレスの保存が必要	✅
画面上のダイアログ、キュー、履歴、イベント	❌	✅

プリンターが応答する場合は、直接接続が使用されます。応答しない場合、または Connect 専用の機能を使う場合は、ツールは Connect 経由で処理します。どちらの方法も利用できるツールの結果には、使用した方法（via）が示されます。それ以外のツールでは、機能に必要な方法が常に使用されます。

カメラ

Buddy3D カメラはプリンターの一部ではありません。Wi-Fi に接続する独立したデバイスで、単独で Prusa Connect と通信し、rtsp://<camera-ip>/live でビデオストリームを配信します。プリンターの PrusaLink にはカメラのエンドポイントがないため（Buddy ファームウェアはエンドポイントを提供しません）、直接接続しただけでは映像を表示できません。カメラの場所を prusactl に指定すると、ffmpeg を使って一度に 1 フレームを取得します。ffmpeg は PATH に含まれている必要があります。

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

スナップショットは、最初に機能したソースから取得します。PrusaLink にある場合はプリンター自体の /api/v1/cameras/snap（ほかの PrusaLink ビルドにはあります）、保存済みの RTSP アドレス、次に Prusa Connect の順です。via: "direct" は最初の 2 つに、via: "connect" は Connect に限定します。PRUSACTL_CAMERA_URL は保存済みのアドレスを上書きします。ユーザー名またはパスワードを含むアドレスは拒否されます。ffmpeg にパスワードをコマンドライン引数として渡すことになり、ローカルのユーザーなら誰でも ps で読み取れるうえ、設定ファイルにも平文で保存されるためです。Buddy3D カメラにはどちらも必要ありません。

プレーンな rtsp:// アドレスのみ受け付けます。rtsps:// は意図的に拒否します。FFmpeg 7.1.5 は自己署名証明書で TLS ハンドシェイクを完了し、-tls_verify 1 と -ca_file を指定してもカメラの認証情報を送信します。RTSP コードから TLS レイヤーにこれらのオプションが渡されないためです。Buddy3D カメラはプレーンな RTSP を配信するため、これによる不都合はありません。残るリスクとして、プレーンな RTSP ではビデオが暗号化されずに送信されるため、ネットワーク上の誰でも視聴できます。信頼できないネットワークにカメラを接続しないでください。

Prusa Connect へのサインイン

prusactl login は Prusa Account のメールアドレスとパスワードに加え、アカウントで 2FA が有効な場合は 2FA コードを求めます。ブラウザーと同じ方法で、HTTPS 経由で Prusa 独自のログインページに情報を入力します。次に、Connect ウェブアプリの OAuth + PKCE フローを使って、取得したコードをトークンと交換します。

AI エージェントに代わりにサインインさせる場合。 prusactl login --manual はパスワードを受け取りません。Prusa Account のリンクを単独の行に表示し（--no-open を指定しない場合はブラウザーで開きます）、続けて標準入力から 1 行を読み込みます。これは承認後にブラウザーが移動した先のアドレスで、https://connect.prusa3d.com/login/auth-callback?code=...&state=... のような形式です（code= の値だけでも動作します）。エージェントから操作できます。方法については skills/prusactl/SKILL.md を参照してください。ループバックモードはありません。Prusa Account は Connect クライアントへの 127.0.0.1 リダイレクトを拒否するため（「Mismatching redirect URI」）、コードはアドレスバーからしか読み取れません。また、Connect の auth-callback ページが、そのページで発行していない state の場合でもコードをそのまま残すことを前提としています。現時点ではページはそのように動作します。Prusa がこれを変更した場合、トークン取得の段階でサインインに失敗し、修正には prusactl の更新が必要になります。

• パスワードは account.prusa3d.com にのみ送信され、保存されません。
• トークンの保存先： OS のキーチェーン（macOS Keychain、Secret Service、または Windows Credential Manager）に、サービス prusactl として保存されます。ヘッドレス Raspberry Pi など、キーチェーンのないマシンでは、代わりに prusactl の設定ディレクトリに secrets.json が作成され、本人だけが読み取れます。PRUSACTL_KEYRING=file を指定すると、こちらを強制的に使用します。
• サインイン状態の維持： トークンは自動的に更新されます。Prusa はリフレッシュトークンをローテーションするため、プロセス間で更新を調整します。複数のエージェントが互いにサインアウトさせることなく、1 つのセッションを共有できます。
• Google または Apple でサインインするアカウントでは、利用する前に Prusa Account のパスワードを設定する必要があります。

プリンターの PrusaLink パスワードも同じキーチェーンに保存されます。

MCP ツール

ツール	経路	機能
connection_status	両方	現在、プリンターに接続する方法と、設定すべき項目
list_printers, get_printer	両方	状態、温度、ジョブの進行状況、および（Connect 経由の場合）画面上のダイアログ
list_printer_files, delete_printer_files	両方	プリンターのストレージを閲覧または整理
download_printer_file	direct	プリンターからこのコンピューターにファイルをコピーします。たとえば、プリントに使用されたスライサー設定を確認できます
upload_file	両方	ローカルの .bgcode／.gcode をプリンターに送信し、必要に応じてプリントを開始またはキューに追加
start_print	両方	プリンターに保存済みのファイルをプリント
control_print	両方	一時停止、再開、または停止
get_transfers	両方	進行中のファイル転送
run_gcode	direct	プリンターがアイドル状態のときに、加熱、原点復帰、移動、フィラメント交換などの G-code を実行
get_camera_snapshot	両方	カメラ画像を取得します。アドレスが保存されていればカメラの 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	両方	その他のエンドポイント。/api/... はプリンターに、/app/... は Connect に送信

すべての printer 引数には、名前、シリアル番号、または Connect UUID を指定できます。プリンターが 1 台だけの場合は省略できます。via: "direct" または via: "connect" を指定すると、経路を固定できます。

CLI

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 サーバーが公開するツールそのものをインメモリ接続経由で実行します。そのため、CLI とエージェントは同じコードパスと同じ安全チェックを通じてプリンターにアクセスし、どちらか一方にしかできない操作はありません。ほとんどのコマンドでは、プリンターを選択する --printer NAME と、経路を固定する --via direct または --via connect を指定できます。各コマンドで指定できる項目は prusactl help <command> で確認できます。すべてのコマンドで --json を指定できます。

同じプラットフォーム確認が適用されます。プリントが完了または停止した後、ジョブを開始するコマンドは、プラットフォーム上に何もないかを確認します。スクリプトでは --plate-clear を指定すると、空であることを確認したものとして扱います。

prusactl help <command>（または <command> --help）でコマンドとそのフラグについて確認できます。フラグは引数の前後どちらにも指定できます。コマンド、フラグ、およびその値はタブ補完できます。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 のキーが含まれます）。そのため、出力を安全に貼り付けたり、エージェントに渡したりできます。--raw を指定すると、マスクせずに表示します。

ファームウェア

prusactl firmware は、プリンターで実行されているファームウェアと、Prusa Connect が提供する最新のファームウェアを表示します。prusactl firmware update は、Connect にホストされている .bbf をプリンターの USB ドライブにコピーしてから、FLASH コマンドでインストールします。 この処理によってプリンターが再起動します。コピーが完了するまで待機します。--version を指定しない場合は、 Connect 独自の判定に従い、判定結果がない場合は判断を拒否します。

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

FLASH が受け付けられるのは、プリンターがアイドル、準備完了、完了、または停止の状態にある場合のみです。 プリント中はコピーを始める前に拒否されるため、プリント終了後にもう一度実行してください。アップデートが必要かどうかは Prusa Connect 独自の判定に従うため、--version を指定しない限り、Connect が提供する最新のファームウェアより 新しいプリンターのファームウェアがダウングレードされることはありません。プリンターの画面で確認を求められる場合があります。 ファームウェアの取得には Prusa Connect のみを使用するため、prusactl login が必要です。

制限事項

• 手作業はできません。 ビルドプレートの清掃、スプールの交換、詰まりの解消はできません。ツールの説明では、 プリントの開始や何かの移動を行う前に、エージェントがプリンター（カメラがある場合はカメラも）を確認するよう指示しています。 ジョブを開始するツールは、プリンターが使用中の場合は拒否します。プリントが完了または停止した後は、ジョブを開始する操作や プレートに向けて移動する操作（start_print、プリントを伴う upload_file、run_gcode、 send_command の HOME、MOVE、MOVE_Z、MESH_BED_LEVELING、または START_PRINT）には、 plate_clear: true も必要です。直前の造形物がまだ残っている可能性があるためです。プリンターを準備完了状態にする操作も、 同じ確認にあたります。api_request は生のアクセスであり、これらのチェックを省略します。
• plate_clear はエージェント自身による申告です。 プレートが空かどうかを確認する手段はないため、ツールの説明では、 値を渡す前にカメラのスナップショットまたはユーザーの申告で確認するようエージェントに指示しています。削除は取り消せません。 問題があるように見えるプリントでは、まず一時停止することを推奨します。
• run_gcode は小さなプリントジョブとして実行されます。 そのため、プリンターがアイドル状態のときのみ動作し、 プリンターの履歴に記録されます。また、プリンターに /usb/prusactl-macro.gcode というファイルが残り、 実行するたびに上書きされます。
• Connect の API は非公式です。 Prusa はこれを公開していません。prusactl は connect.prusa3d.com と同じ エンドポイントを使用しているため、Prusa 側の変更によって Connect のルートが動作しなくなる場合があります。 直接接続するルートでは、Prusa がドキュメント化している PrusaLink API を使用します。 どちらかに変更があった場合、prusactl は誤動作せずに、想定されるメッセージを表示します。「このバージョンの prusactl が認識できない応答を Prusa Connect が返しました：…」という形式で、リクエストと想定外の内容が示されます。通常は prusactl を更新すると解決します。 最新版でも解決しない場合は、このメッセージを添えて issue を報告してください。

設定

変数	用途
PRUSACTL_HOST、PRUSACTL_USER、PRUSACTL_AUTH	保存済みのプリンターアドレス、ユーザー名、または digest／api-key を上書きします
PRUSACTL_PASSWORD、PRUSACTL_API_KEY	キーチェーンの代わりにプリンターのシークレットを指定します
PRUSACTL_KEYRING=file	OS のキーチェーンの代わりに、認証情報を 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 のウェブアプリのもの）

開発

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

リリースは vX.Y.Z タグをプッシュして作成します。CI がバイナリをビルドし、Homebrew tap を更新し、MCP バンドルを添付して、 MCP Registry に公開します。CHANGELOG.md を参照してください。

ライセンス

MIT。

prusactl は独立したプロジェクトです。Prusa Research とは提携しておらず、同社からの推奨も受けていません。 Prusa および Prusa Connect は、Prusa Research a.s. の商標です。