PrintGo lets an AI assistant print to the printers on your computer. It's an
MCP server: once your MCP client is
connected to it, the assistant can list your printers, send them PDFs, images,
text, Markdown, or HTML, and check on the jobs afterwards.
PrintGo runs on the computer the printer is connected to and puts itself
behind a Cloudflare tunnel, so your assistant can reach it from anywhere: a
cloud agent, another laptop, or the same machine.
Print PDFs, images, text, Markdown and HTML to your local printers, and track or cancel the jobs.
2026-11-09
星數
—
工具
—
可用率
—
What you need
Node.js 22.12 or newer.
macOS, Linux, or Windows, with a printer your operating system already knows
about. PrintGo doesn't install drivers; it talks to the print system you
already have:
macOS and Linux use CUPS (the lp, lpstat, lpoptions, and cancel
commands).
Windows uses PowerShell and SumatraPDF.
PrintGo turns everything into a PDF before printing, so SumatraPDF is
needed for every job, not just PDFs. It should be on your PATH, or you
can point to it with --sumatra-pdf <path>.
Chrome or Chromium, but only if you want to print Markdown or HTML. If you
don't have either, printgo install-browser will download one. To use a
specific browser, pass --chrome <path> or set PRINTGO_CHROME_PATH.
Getting started
Install the CLI:
npm install -g printgo
Then start it:
printgo start
This starts PrintGo in the background along with a Cloudflare tunnel, then
prints an MCP URL and a password. Add that URL to your MCP client and send the
password as an Authorization: Bearer <password> header. Your client needs
to support MCP's Streamable HTTP transport; the older SSE transport isn't
supported.
The password is generated the first time you run start and reused after
that. Treat it like a key to your printer: anyone who has it can print, and
can cancel jobs PrintGo has submitted. Traffic goes through Cloudflare.
PrintGo needs cloudflared for the tunnel. If it can't find one, it asks
before downloading the official release from GitHub. Pass --yes to skip the
question (you'll need this when there's no terminal to answer it), or
--no-download to fail instead. If cloudflared lives somewhere unusual,
pass --cloudflared <path>.
If you'd rather not install globally, npx printgo <command> works too. The
package also installs a printgo-mcp command, which is the same thing under
another name.
Managing the server
printgo status
printgo stop
printgo restart
restart reuses the settings from your last start. If something goes wrong,
the background server's log is at ~/.printgo/daemon.log.
By default you get a Cloudflare Quick Tunnel, which needs no Cloudflare
account, but its URL changes every time PrintGo starts. If you have a domain on
Cloudflare, you can give PrintGo a stable address instead:
If cloudflared isn't logged in to your Cloudflare account yet, this opens a
browser so you can log in. PrintGo then creates a tunnel in your account (or
reuses one it made before) and adds a DNS record for that hostname. It won't
overwrite a DNS record that already exists.
Custom domain settings are saved, so later start and restart calls reuse
them. Pass --quick to use a Quick Tunnel for a particular run. You can also
connect a tunnel you already have, or use a token from the Cloudflare
dashboard; printgo start --help lists all the options. Add --json to
start, stop, status, or restart if you're calling them from a script.
Local only, without a tunnel
If your MCP client runs on the same computer as the printer, you can skip the
tunnel and let the client launch PrintGo directly over stdio:
You don't run printgo start in this mode. The client starts PrintGo when it
needs it and shuts it down when it's done, and there's no password or
Cloudflare involved.
What the assistant can do
PrintGo gives the assistant seven tools:
Tool
What it does
listPrinters
Lists the printers set up on your computer
getPrinterCapabilities
Shows the options a printer's driver supports
checkPrinterStatus
Shows a printer's current state, such as idle or printing
sendPrintCommand
Prints a PDF, PNG, JPEG, or plain text file from an HTTPS URL
printMarkup
Renders Markdown or HTML and prints it
getPrintJobStatus
Checks on a job PrintGo submitted
cancelPrintJob
Cancels a job PrintGo submitted
When printing, the assistant can choose the number of copies (up to 100), page
ranges, paper size, orientation, single- or double-sided, color or black and
white, and whether to fit the content to the page.
A few things worth knowing:
Files come from URLs, not your disk. The assistant passes a public HTTPS
link and PrintGo downloads it. Signed links work. Local file paths and
private network addresses are refused, including through redirects, so a
prompt can't trick PrintGo into printing something off your machine or your
local network. Downloads are capped at 10 MiB.
Link to the file itself.sendPrintCommand wants a direct download, not a
web page that displays the file. To print HTML, use printMarkup.
Markdown and HTML can be passed inline (up to 32 KiB) or by URL (up to
1 MiB). PrintGo renders them in headless Chrome with scripts disabled. Images
and stylesheets they link to must also be public HTTPS URLs.
Word, Excel, and other Office files aren't supported. Convert them to PDF
first. PrintGo works out whether a URL is text from its file extension or the
server's content type; if it can't tell, set assetType: 'text'.
Retries won't print twice. Every print request carries an
idempotencyKey. If the assistant retries with the same key and arguments,
PrintGo returns the original job instead of printing again. Reusing a key
with different arguments is an error. A new key means a new print.
Job status only reflects the print queue. Printers don't report whether
paper actually came out. On macOS and Linux, completed means the job left
the queue, which also happens when a job fails or is cancelled outside
PrintGo. On Windows, a job that has left the queue shows as unknown.
Where PrintGo keeps its state
PrintGo keeps everything in ~/.printgo: the remote password, tunnel settings,
job history, idempotency keys, logs, and any cloudflared or Chrome it
downloaded. You can point it somewhere else with --state-dir, the
PRINTGO_HOME environment variable, or the stateDir option in the SDK.
If you run more than one PrintGo server at a time, for example the background
server and a stdio one, give each its own directory so they don't step on each
other's job history.
Using it as a library
The same package can be used from your own Node code:
npm install printgo
Talking to a PrintGo server
connectPrinter gives you a typed client, so you can call the tools as
ordinary functions:
The URL must be HTTPS, except for localhost during development.
To talk to a local server over stdio instead, pass
{ transport: new StdioClientTransport({ command, args }) }, importing
StdioClientTransport from @modelcontextprotocol/client/stdio. The client
opens and closes the transport for you.
Running the server yourself
To serve over stdio from your own process:
import { servePrinterStdio } from 'printgo';
const server = servePrinterStdio();
// It closes by itself when stdin ends, or you can call: await server.close();
If you want more control, there are two lower-level options:
createPrinterMcpServer(options?) returns an MCP server that isn't connected
to anything yet, so you can attach your own transport.
createPrinterHttpServer({ password, ...options }) returns an HTTP server
with listen(), close(), and setPublicURL(). It serves MCP at /mcp,
only listens on 127.0.0.1, and requires a password of at least 32
characters. If you put it behind your own proxy, call setPublicURL() with
the public address; requests for any other hostname are rejected.
Neither one starts a tunnel. Both accept stateDir, adapter,
assetDownloader, sumatraPdfPath, and browserExecutablePath. If you
supply your own assetDownloader, you're taking over PrintGo's URL, size, and
timeout checks, so make sure yours does the same.
Managing the tunnel from code
The hosting commands live in a separate entry point:
configureCloudflare and ensureCloudflared are exported from there as well.
Working on PrintGo
From a clone of this repo:
npm install
npm test
npm run typecheck
npm test builds first. The tests use fake printers and a fake cloudflared,
so they won't print anything or touch Cloudflare. The Markdown and HTML
rendering tests need a local Chrome or Chromium and are skipped if there isn't
one; set REQUIRE_CHROMIUM_TESTS=1 to make that a failure instead.
npm run smoke:tunnel starts a real Quick Tunnel and checks that an
authenticated MCP client can reach PrintGo through it, without printing
anything. It needs cloudflared installed, or run
npm run smoke:tunnel -- --yes to let it download one.
Before publishing, npm pack --dry-run shows what will go into the package.
License
MIT. The bundled Noto Sans font is under the SIL Open Font License.