thermal-mcp 🧾

Print beautiful HTML & Markdown on a $30 thermal receipt printer, straight from your AI agent.

thermal-mcp is an MCP server that turns any 58mm ESC/POS thermal printer into a typographic output device for LLM agents. The agent hands over Markdown or HTML; the server renders it in headless Chromium (2× supersampled), converts it to 1-bit with quality dithering, encodes ESC/POS, and ships it to the printer over USB, Bluetooth serial, or CUPS — wired preferred, automatically.

agent ──MCP──► render (Chromium @2x) ──► 1-bit (Atkinson/Jarvis/Bayer + CLAHE)
              ──► ESC/POS (heat-tuned, blank-line elision) ──► USB / BT / CUPS

Why it's nice

• Markdown in, ticket out — GFM plus syntax-highlighted code (monochrome scheme), mermaid diagrams, LaTeX math (KaTeX), task lists, tables, remote images. Three type-size tiers.

• Full custom HTML when the agent wants layout control: real Chromium, so flexbox/grid/SVG/emoji/web fonts all work.

• Offline font library — Geist Sans/Mono, Inter, JetBrains Mono, Space Grotesk, Lora, Playfair Display, Caveat, Noto Sans SC, plus Font Awesome icons, all bundled and loaded via file://.

• Print quality obsessed — supersampled rendering, CLAHE + unsharp photo pipeline, three dither algorithms, ESC/POS heat/density tuning (ESC 7, DC2 #), blank-line elision, paced Bluetooth writes. Calibrated on real hardware.

• Exact previews — preview_* tools return the true 1-bit image that will print, so agents iterate without wasting paper.

• <img data-qr="..."> becomes a scannable QR code, generated server-side.

Tools

mode: auto (detect photos, keep text sharp) / text / photo · algorithm: atkinson / jarvis / bayer · size: large 24px / medium 19px / small 14px.

Setup

git clone https://github.com/EthanPany/thermal-mcp && cd thermal-mcp
npm install
npx puppeteer browsers install chrome
npm run smoke   # renders out/smoke.png without a printer

Register with Claude Code:

claude mcp add --scope user thermal --env THERMAL_TRANSPORT=auto \
  -- "$(which node)" /absolute/path/to/thermal-mcp/node_modules/tsx/dist/cli.mjs \
     /absolute/path/to/thermal-mcp/src/index.ts

Claude Desktop (claude_desktop_config.json). Use absolute paths — GUI apps launch with a minimal PATH and won't find npx/tsx on their own:

"thermal": {
  "command": "/absolute/path/to/node",
  "args": [
    "/absolute/path/to/thermal-mcp/node_modules/tsx/dist/cli.mjs",
    "/absolute/path/to/thermal-mcp/src/index.ts"
  ],
  "env": { "THERMAL_TRANSPORT": "auto" }
}

Design guidance. In Claude Code, optionally install the skill so it auto-loads:

ln -s /absolute/path/to/thermal-mcp/skills/thermal-print ~/.claude/skills/thermal-print

In Claude Desktop (or any other MCP client) the skill mechanism isn't available, but the same guidance is served over MCP by the design_guide tool — the agent calls it before designing. No extra setup.

Printer configuration

THERMAL_TRANSPORT=auto (default) probes in order: USB (any printer-class device) → Bluetooth SPP serial (THERMAL_DEVICE, default /dev/cu.MPT-II) → dry-run (writes PNG + ESC/POS bytes to out/). Or force usb / serial / lp-raw / lp-image / file.

Darkness: by default the server sends only ESC @ and uses the printer's firmware-default darkness — clean, no bleed. Hardware heat/density commands are opt-in because some clone firmwares (incl. the MPT-II tested here) misparse ESC 7 and leak a parameter byte as a stray glyph. Set these only if your firmware honors them and you need to push darker:

Tested on a Sunydog 58mm (USB 6868:0200, Bluetooth "MPT-II") on macOS. Any printer speaking GS v 0 raster should work.

License

MIT