PrintGo README

PrintGo-MCP

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.

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:

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

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:

{
  "mcpServers": {
    "printgo": {
      "command": "printgo",
      "args": ["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:

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:

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();
}

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:

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

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

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.