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

tool	what it does
print_markdown { markdown, size?, feed_lines? }	quick path: markdown → house-styled ticket
preview_markdown { markdown, size? }	exact 1-bit preview, no paper
print_html { html, mode?, algorithm?, feed_lines? }	full custom design
preview_html { html, mode?, algorithm? }	exact 1-bit preview
printer_status {}	transport + printer state
design_guide {}	returns the full design guide (fonts, layout, house style) — client-agnostic, works in Claude Desktop

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:

env	meaning	default
THERMAL_HEAT_TIME	ESC 7 n2 — heat pulse ×10µs (darker); enables ESC 7	unset
THERMAL_HEAT_DOTS	ESC 7 n1 — dots per strobe = 8×(n+1)	3 (if ESC 7 on)
THERMAL_HEAT_INTERVAL	ESC 7 n3 — recovery ×10µs (fixes fading)	60 (if ESC 7 on)
THERMAL_DENSITY	DC2 # density 0–31; enables DC2 #	unset
THERMAL_BREAK	DC2 # per-line break time 0–7	4 (if DC2 # on)
THERMAL_THIN	software stroke-thinning 0–2 (0.3–0.6 lightens fat Latin text; >0.7 breaks small/CJK text)	0 (off)
THERMAL_MAX_PX	max ticket height in px; taller content is truncated with a warning (roll-saver)	12000 (~1.5m)
THERMAL_DITHER	default photo algorithm	atkinson
THERMAL_CHUNK / THERMAL_PACE_MS	Bluetooth pacing	256 / 30

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

License

MIT