PrintGo

PrintGo-MCP

PrintGo を使うと、AI アシスタントからコンピューターに接続されているプリンターへ印刷できます。これは MCP サーバーです。MCP クライアントを接続すると、アシスタントはプリンターの一覧表示、PDF、画像、テキスト、Markdown、HTML の送信、印刷後のジョブの確認ができます。

PrintGo はプリンターに接続されているコンピューター上で動作し、Cloudflare トンネルの背後に配置されるため、クラウドエージェント、別のノートパソコン、同じコンピューターなど、どこからでもアシスタントがアクセスできます。

必要なもの

• Node.js 22.12 以降。
• macOS、Linux、または Windows と、オペレーティングシステムがすでに認識しているプリンター。PrintGo はドライバーをインストールしません。既存の印刷システムを使用します。
  • macOS および Linux では CUPS（lp、lpstat、lpoptions、cancel コマンド）を使用します。
  • Windows では PowerShell と SumatraPDF を使用します。PrintGo は印刷前にすべてを PDF に変換するため、PDF 以外の印刷ジョブにも SumatraPDF が必要です。SumatraPDF が PATH に設定されている必要があります。または、--sumatra-pdf <path> でパスを指定できます。
• Chrome または Chromium。ただし、Markdown または HTML を印刷する場合に限り必要です。どちらもインストールされていない場合は、printgo install-browser でダウンロードできます。特定のブラウザーを使うには、--chrome <path> を渡すか、PRINTGO_CHROME_PATH を設定してください。

はじめに

CLI をインストールします。

npm install -g printgo

次に起動します。

printgo start

これにより、PrintGo が Cloudflare トンネルとともにバックグラウンドで起動し、MCP URL とパスワードが表示されます。その URL を MCP クライアントに追加し、Authorization: Bearer <password> ヘッダーとしてパスワードを送信してください。クライアントは MCP の Streamable HTTP トランスポートに対応している必要があります。以前の SSE トランスポートには対応していません。

パスワードは start の初回実行時に生成され、以降は同じものが再利用されます。プリンターの鍵と同じように扱ってください。パスワードを持つ人は誰でも印刷でき、PrintGo が送信したジョブをキャンセルできます。通信は Cloudflare を経由します。

トンネルには cloudflared が必要です。見つからない場合、PrintGo は GitHub から公式リリースをダウンロードする前に確認を求めます。質問を省略するには --yes を渡してください（確認に応答できるターミナルがない場合は必須です）。ダウンロードせずに失敗させるには --no-download を渡します。cloudflared が通常とは異なる場所にある場合は、--cloudflared <path> を渡してください。

グローバルにインストールしたくない場合は、npx printgo <command> も使えます。このパッケージでは printgo-mcp コマンドもインストールされます。これは別名で同じコマンドです。

サーバーの管理

printgo status
printgo stop
printgo restart

restart は直前の start で使用した設定を再利用します。問題が発生した場合は、バックグラウンドサーバーのログを ~/.printgo/daemon.log で確認できます。

デフォルトでは Cloudflare Quick Tunnel が使われます。Cloudflare アカウントは不要ですが、PrintGo の起動ごとに URL が変わります。Cloudflare にドメインがある場合は、代わりに固定アドレスを PrintGo に設定できます。

printgo stop
printgo start --custom-domain-with-cf printer.example.com

cloudflared がまだ Cloudflare アカウントにログインしていない場合は、ログイン用のブラウザーが開きます。PrintGo はアカウントにトンネルを作成するか、以前作成したトンネルを再利用し、そのホスト名に DNS レコードを追加します。すでに存在する DNS レコードは上書きしません。

カスタムドメインの設定は保存されるため、以降の start および restart の実行時に再利用されます。特定の実行で Quick Tunnel を使うには --quick を渡してください。すでにあるトンネルに接続したり、Cloudflare ダッシュボードから取得したトークンを使用したりすることもできます。すべてのオプションは printgo start --help で確認できます。スクリプトから start、stop、status、restart を呼び出す場合は、--json を追加してください。

トンネルなしでローカルのみで使う

MCP クライアントがプリンターと同じコンピューター上で動作する場合は、トンネルを省略し、クライアントから stdio 経由で PrintGo を直接起動できます。

{
  "mcpServers": {
    "printgo": {
      "command": "printgo",
      "args": ["stdio"]
    }
  }
}

このモードでは printgo start を実行しません。クライアントは必要なときに PrintGo を起動し、使い終わると終了します。パスワードも Cloudflare も必要ありません。

アシスタントにできること

PrintGo はアシスタントに 7 つのツールを提供します。

ツール	機能
listPrinters	コンピューターに設定されているプリンターを一覧表示します
getPrinterCapabilities	プリンタードライバーがサポートするオプションを表示します
checkPrinterStatus	待機中や印刷中など、プリンターの現在の状態を表示します
sendPrintCommand	HTTPS URL から PDF、PNG、JPEG、またはプレーンテキストファイルを印刷します
printMarkup	Markdown または HTML をレンダリングして印刷します
getPrintJobStatus	PrintGo が送信したジョブの状態を確認します
cancelPrintJob	PrintGo が送信したジョブをキャンセルします

印刷時、アシスタントは部数（最大 100 部）、ページ範囲、用紙サイズ、向き、片面または両面、カラーまたは白黒、コンテンツをページに合わせるかどうかを指定できます。

知っておくべき点がいくつかあります。

• ファイルの取得元はディスクではなく URL です。 アシスタントは公開 HTTPS リンクを渡し、PrintGo がファイルをダウンロードします。署名付きリンクも使用できます。リダイレクト経由も含め、ローカルファイルパスとプライベートネットワークアドレスは拒否されます。そのため、プロンプトによって PrintGo がコンピューターやローカルネットワーク上のファイルを印刷させられることはありません。ダウンロードサイズの上限は 10 MiB です。
• ファイルそのものへのリンクを指定してください。 sendPrintCommand が必要とするのは、ファイルを表示するウェブページではなく、ファイルの直接ダウンロードリンクです。HTML を印刷するには printMarkup を使用してください。
• Markdown と HTML はインライン（最大 32 KiB）または URL（最大 1 MiB）で渡せます。 PrintGo はスクリプトを無効にしたヘッドレス Chrome でレンダリングします。リンク先の画像とスタイルシートも公開 HTTPS URL である必要があります。
• Word、Excel などの Office ファイルには対応していません。 まず PDF に変換してください。PrintGo はファイル拡張子またはサーバーのコンテンツタイプから URL がテキストかどうかを判定します。判定できない場合は assetType: 'text' を設定してください。
• 再試行しても二重印刷されません。 すべての印刷リクエストには idempotencyKey が付与されます。同じキーと引数でアシスタントが再試行すると、PrintGo は再印刷せず元のジョブを返します。異なる引数でキーを再利用するとエラーになります。新しいキーを使うと新しい印刷が行われます。
• ジョブの状態に反映されるのは印刷キューの状況だけです。 プリンターは実際に用紙が排出されたかどうかを報告しません。macOS と Linux では、completed はジョブがキューを離れたことを意味します。PrintGo 外でジョブが失敗またはキャンセルされた場合も同様です。Windows では、キューを離れたジョブは unknown と表示されます。

PrintGo が状態を保存する場所

PrintGo は、リモートパスワード、トンネル設定、ジョブ履歴、冪等性キー、ログ、ダウンロードした cloudflared や Chrome など、すべてのデータを ~/.printgo に保存します。--state-dir、PRINTGO_HOME 環境変数、または SDK の stateDir オプションを使って、保存先を変更できます。

バックグラウンドサーバーと stdio サーバーなど、複数の PrintGo サーバーを同時に実行する場合は、それぞれに独自のディレクトリを割り当てて、ジョブ履歴が互いに干渉しないようにしてください。

ライブラリとして使用する

同じパッケージを独自の Node コードから使用できます。

npm install printgo

PrintGo サーバーとの通信

connectPrinter を使うと型付きクライアントが得られるため、ツールを通常の関数として呼び出せます。

import { connectPrinter } from 'printgo';

const printer = await connectPrinter({
  mcpConnectionURL: process.env.PRINTER_URL!,
  password: process.env.PRINTER_PASSWORD!,
});

try {
  const [selected] = await printer.listPrinters();
  if (!selected) throw new Error('No printers configured.');

  await printer.sendPrintCommand({
    printerId: selected.id,
    assetUrl: 'https://example.com/invoice.pdf',
    settings: { copies: 1, paperSize: 'A4' },
    idempotencyKey: 'invoice-123',
  });
} finally {
  await printer.close();
}

開発中の localhost を除き、URL は HTTPS である必要があります。

代わりに stdio 経由でローカルサーバーと通信するには、@modelcontextprotocol/client/stdio から StdioClientTransport をインポートし、{ transport: new StdioClientTransport({ command, args }) } を渡してください。クライアントがトランスポートの接続と切断を行います。

サーバーを自分で実行する

独自のプロセスから stdio 経由で提供するには：

import { servePrinterStdio } from 'printgo';

const server = servePrinterStdio();
// It closes by itself when stdin ends, or you can call: await server.close();

より細かく制御したい場合は、低レベルのオプションが 2 つあります。

• createPrinterMcpServer(options?) は、まだ何にも接続されていない MCP サーバーを返すため、独自のトランスポートを接続できます。
• createPrinterHttpServer({ password, ...options }) は、listen()、close()、setPublicURL() を備えた HTTP サーバーを返します。/mcp で MCP を提供し、127.0.0.1 のみでリッスンします。また、32 文字以上のパスワードが必要です。独自のプロキシの背後に配置する場合は、公開アドレスを指定して setPublicURL() を呼び出してください。それ以外のホスト名へのリクエストは拒否されます。

どちらもトンネルを開始しません。どちらも stateDir、adapter、assetDownloader、sumatraPdfPath、browserExecutablePath を受け付けます。独自の assetDownloader を指定すると、PrintGo が行う URL、サイズ、タイムアウトのチェックを引き継ぐことになるため、同じチェックを実装してください。

コードからトンネルを管理する

ホスティングコマンドは、別のエントリーポイントにあります。

import { start, stop, status, restart } from 'printgo/hosting';

const connection = await start({ downloadCloudflared: true });
// connection.mcpConnectionURL, connection.password

configureCloudflare と ensureCloudflared もそこからエクスポートされています。

PrintGo の開発

このリポジトリをクローンした状態で、次のコマンドを実行します。

npm install
npm test
npm run typecheck

npm test は最初にビルドを実行します。テストでは偽のプリンターと偽の cloudflared を使用するため、印刷や Cloudflare へのアクセスは行いません。Markdown と HTML のレンダリングテストにはローカルの Chrome または Chromium が必要です。どちらもない場合、テストはスキップされます。代わりに失敗として扱うには、REQUIRE_CHROMIUM_TESTS=1 を設定します。

npm run smoke:tunnel は実際の Quick Tunnel を起動し、認証済みの MCP クライアントがそのトンネル経由で PrintGo にアクセスできることを、何も印刷せずに確認します。cloudflared がインストールされている必要があります。ダウンロードを許可するには、npm run smoke:tunnel -- --yes を実行してください。

公開する前に、npm pack --dry-run を実行するとパッケージに含まれる内容を確認できます。

ライセンス

MIT です。同梱されている Noto Sans フォントは、SIL Open Font License の下で提供されています。