print-mcp

Tell your AI "print this" and it prints. Plug the printer in, and the AI handles the rest: finding it, drivers, stuck queues and errors.

An MCP server that finds every printer on your LAN, remembers them, and prints PDFs, Office files, images, web pages and plain text in one tool call, with exact control over borders, color, darkness and quality. When something goes wrong, one more call diagnoses it and repairs what software can repair.

Install

You need Node.js 20.11 or newer. Then, in any terminal:

npm install -g https://github.com/Kritsanai-Krish/print-mcp/releases/latest/download/print-mcp.tgz

print-mcp setup

setup adds the server to every AI client it finds (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Gemini CLI, Codex) and scans for printers, so the first print starts instantly. Each config file it changes is backed up first. A file it cannot parse is left alone and reported.

Restart your AI client and you're done. To update, run both commands again. To remove it:

print-mcp uninstall

npm uninstall -g print-mcp

Using another client? Point it at print-mcp serve over stdio.

Related MCP server: printagent

Use it

Just say it, in any language:

Print report.pdf

Print pages 1-3 of report.docx, 2 copies, black and white, with a 1 mm border

Print this page 2-up, darker, with a "DRAFT" watermark: https://example.com/spec

If you have one printer, or only one is on, it is used without asking. Otherwise the choice falls to your saved default, then the Windows default, then the most recently used. The AI only asks when the choice is truly open.

Tools

Sources: PDF, JPEG, PNG, WebP, TIFF, GIF, HEIC, Word, Excel, PowerPoint, RTF, HTML, Markdown, CSV, text and code (UTF-8, UTF-16, TIS-620), XPS, EPUB, URLs, data: URIs.

Settings: paper, type, tray, pages, odd/even, reverse, copies, collate, duplex, orientation, rotate, scale mode, exact zoom, margins per side, borderless, alignment, n-up, frame thickness/color/style/gap, cell frames, color mode, quality, dpi, darkness, brightness, contrast, saturation, gamma, sharpen, ink saver, black-and-white threshold, invert, mirror, watermark, header, footer, fonts, line height, line numbers, CSS.

When something goes wrong

Just tell the AI. fix_printer checks everything and answers with what it fixed and what only you can do.

Repairs that need admin rights raise the Windows permission prompt, so you stay in charge. Set "allowElevation": false in config.json to turn them off.

Platforms

Real-hardware testing so far is one printer on Windows, a Brother DCP-T520W over Wi-Fi. macOS and Linux run the test suite in CI against a mock printer. Reports from other printers are welcome.

How it stays instant

• Stale-while-revalidate discovery. printers.json answers at once. mDNS, a /24 TCP sweep and the Windows spooler refresh it in the background.

• Identity is the UUID, not the IP. A DHCP change is healed by a rescan the moment the old address stops answering. Windows WSD ports store the same UUID as IPP printer-uuid, so the queue and the device merge exactly, never by guessing from names.

• Pages stream while they render. print returns once page 1 is on its way. Rendering is lazy, so memory stays near one page even at 600 dpi.

Why it renders its own pixels

Printers offer very few job attributes, and none for ink density or a printed frame. Working on the page raster makes those settings behave the same on every printer.

printer has IPP  -> PDF untouched if it takes PDF and no pixel edits were asked
                 -> URF or PWG Raster, whichever it prefers
                 -> image PDF, then PCL, then JPEG
no IPP, has Windows queue -> render, then draw through the driver (USB, shared, driver-only)
only port 9100   -> PCL mono raster

Pages with no color are sent as gray automatically, so black text uses no color ink.

Safety rules built in

• A missing path is an error, never printed as literal text. Error pages (HTTP 4xx/5xx) are never printed.

• The same document on the same printer within 20 s is treated as an accidental retry.

• More than 50 sheets needs confirm_large.

• Once data has been sent, a job is never retried automatically, because that could print twice.

• Macros stay off for Office files. Only the Office process this tool started is ever closed.

• Printing through a Windows queue restores the default printer afterwards.

• Plain IPP is refused beyond private addresses. IPPS uses trust-on-first-use certificate pinning.

• Inline HTML runs with no scripts and no network unless asked.

• URLs on private addresses and \\server\share paths need allow_private_network. Every redirect hop and browser request is checked.

• Markdown reads only pictures from its own folder; an HTML file reads only its own folder. No other local file can end up on paper.

• output_file only works on virtual queues, needs a document extension and never overwrites.

• Text from printers is cut short and stripped before it reaches the AI.

• Driver installers must carry a valid digital signature, checked again just before they run. Admin repairs are a fixed list of actions in scripts/elevated.ps1, and each one needs your yes at the Windows prompt.

• Queued jobs are only removed when they are in error, never ones merely waiting for paper. Dropping everything needs clear_all_jobs.

The server only talks over stdio; it opens no listening port. Please report security problems through a private advisory.

Known limits

• A subresource that redirects to an internal address, and DNS rebinding, can get past the browser's address check. The fetch path checks each hop, but Playwright routing does not see browser-followed redirects.

• Word can still fetch a remote template named inside a .docx when it opens the file.

• Duplex, PCL and TLS paths are covered by the mock printer only; they have not run on real hardware.

• Printers that need IPP login, or accept only PCLm or PostScript, must go through their Windows driver queue.

• Paper, jams, ink and first-time Wi-Fi setup need a person. No software can do these.

• A signature proves who published an installer, not that it is safe. Windows Protected Print blocks third-party drivers altogether.

• A Windows queue with a TCP port pointing at an old IP is reported through its status but not re-pointed. Printing still works directly over the network.

Develop

git clone https://github.com/Kritsanai-Krish/print-mcp.git

cd print-mcp

npm install

npm test

Tests use a mock IPP printer and, on Windows, Microsoft Print to PDF, so they use no paper. node dist/cli.js setup registers your local build. After changing code, run npm run build, because clients run dist/index.js.

• src/ipp.ts IPP client and bounds-checked decoder

• src/raster.ts URF, PWG and PCL encoders

• src/discovery.ts, src/registry.ts finding printers, merging, choosing one

• src/options.ts settings schema, fitting a request to a printer

• src/sources.ts any input to a paged document

• src/render.ts layout, tone, frames, overlays

• src/jobs.ts routes, queueing, status

• src/doctor.ts diagnosis, repairs, driver install

• src/cli.ts installer

• scripts/*.ps1 Windows queue listing, driver printing, Office conversion, repairs

State lives in %LOCALAPPDATA%\print-mcp on Windows and ~/.local/share/print-mcp elsewhere. PRINT_MCP_HOME overrides it.

To release, bump version in package.json and push a matching tag such as v1.0.1. The workflow tests it and publishes the package the install command downloads.

License

AGPL-3.0-or-later, because the PDF engine, MuPDF, is AGPL. Using this tool yourself brings no obligations. If you distribute a modified version or offer it as a network service, you must share your source under the same license.