# thermal-mcp 🧾

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

thermal-mcp is an [MCP](https://modelcontextprotocol.io) 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

```sh
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:

```sh
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:

```json
"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:

```sh
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