PrintGo

PrintGo-MCP

PrintGo 可让 AI 助手使用你电脑上的打印机进行打印。它是一个 MCP 服务：MCP 客户端连接后，助手便可以列出你的打印机，向它们发送 PDF、图像、文本、Markdown 或 HTML，并在之后查看打印作业。

PrintGo 在连接打印机的电脑上运行，并通过 Cloudflare 隧道对外提供服务，因此你的助手可以从任何地方访问它：无论是云端 Agent、另一台笔记本电脑，还是同一台电脑。

所需条件

• Node.js 22.12 或更高版本。
• macOS、Linux 或 Windows，以及操作系统已识别的打印机。PrintGo 不会安装驱动程序，而是使用你已有的打印系统：
  • macOS 和 Linux 使用 CUPS（lp、lpstat、lpoptions 和 cancel 命令）。
  • Windows 使用 PowerShell 和 SumatraPDF。PrintGo 会先将所有内容转换为 PDF 再进行打印，因此每个打印作业都需要 SumatraPDF，而不仅仅是 PDF 作业。SumatraPDF 应位于你的 PATH 中，也可以通过 --sumatra-pdf <path> 指定其路径。
• 只有在需要打印 Markdown 或 HTML 时，才需要 Chrome 或 Chromium。如果两者都没有，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。

PrintGo 需要 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。

默认情况下，PrintGo 会使用 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 可在某次运行中使用 Quick Tunnel。你也可以连接已有隧道，或使用 Cloudflare 控制面板中的令牌；printgo start --help 列出了所有选项。如果通过脚本调用 start、stop、status 或 restart，可以添加 --json。

仅本地运行，不使用隧道

如果 MCP 客户端与打印机位于同一台电脑上，你可以跳过隧道，让客户端直接通过 stdio 启动 PrintGo：

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

在此模式下，无需运行 printgo start。客户端会在需要时启动 PrintGo，并在完成后将其关闭；整个过程不涉及密码或 Cloudflare。

助手可以做什么

PrintGo 为助手提供七种工具：

工具	功能
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 会将所有内容保存在 ~/.printgo 中：远程密码、隧道设置、作业历史记录、幂等键、日志，以及它下载的任何 cloudflared 或 Chrome。你可以通过 --state-dir、PRINTGO_HOME 环境变量或 SDK 中的 stateDir 选项，将其指向其他位置。

如果你同时运行多个 PrintGo 服务，例如后台服务和 stdio 服务，请为每个服务指定单独的目录，以免它们的作业历史记录相互干扰。

将其用作库

你也可以在自己的 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 与本地服务通信，请改为传入 { transport: new StdioClientTransport({ command, args }) }，并从 @modelcontextprotocol/client/stdio 导入 StdioClientTransport。客户端会为你打开并关闭传输连接。

自行运行服务

从自己的进程通过 stdio 提供服务：

import { servePrinterStdio } from 'printgo';

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

如果需要更多控制，可以选择以下两种较底层的方式：

• createPrinterMcpServer(options?) 会返回一个尚未连接到任何对象的 MCP 服务，因此你可以为它连接自己的传输方式。
• createPrinterHttpServer({ password, ...options }) 会返回一个 HTTP 服务，提供 listen()、close() 和 setPublicURL()。它会在 /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。