phomemo

Print on a Phomemo M02 Pro pocket thermal printer from your computer, without the phone app. Includes a command-line tool and an MCP server, so Claude and other AI agents can print cards, checklists and pictures for you.

• Markdown in, neat cards out: titles, bullets, checkboxes, numbered lists.

• Pictures are scaled to the paper and dithered for thermal printing.

• Print jobs you can list, cancel (cleanly, between blocks) and reprint.

• Waits for the printer to confirm that each card actually printed.

• Reads battery, paper, lid and temperature.

• Runs locally over Bluetooth LE on macOS and Linux (and in principle Windows, via bleak).

Supported printers

Other Phomemo families (M110, M04, D30, …) use different protocols and aren't supported yet. See Contributing.

Paper: 53mm-wide continuous rolls (e.g. 53mm × 6.5m). The print head covers the middle 48mm (576 dots at 300 dpi).

The M02 Pro's USB-C port only charges. It carries no data, so Bluetooth is the only way to print.

Related MCP server: Memobird MCP Server

Install

uv tool install git+https://github.com/s04/phomemo
# or: pipx install git+https://github.com/s04/phomemo

Requires Python 3.11+.

Use

Turn the printer on and close the Phomemo phone app, because the printer accepts only one connection at a time.

phomemo scan                                  # find printers nearby
phomemo "# Groceries" "- [ ] oat milk" "- [ ] bread"
echo "# Idea" | phomemo                       # from stdin
phomemo -f notes.md                           # from a file
phomemo --preview -f notes.md                 # save a PNG instead of printing
phomemo image photo.jpg                       # print a picture
phomemo status                                # battery, paper, lid, temperature

Card format

# Title                 ← every "# " starts a new card
## Heading
A paragraph of text.
- bullet
1. numbered
- [ ] todo
- [x] done
> aside
---                     ← also starts a new card

The printable width is 48mm (about 25 characters per line), so short cards work best.

Jobs

phomemo jobs                     # recent jobs, status and progress
phomemo cancel                   # stop everything queued or printing
phomemo cancel 0923-1651         # stop one job (any unique id prefix)
phomemo reprint                  # print the last job again

• Ctrl-C cancels cleanly; press it twice to force quit.

• Cancelling stops between image blocks (at most about 2cm of paper) and feeds the paper out. The printer is left ready for the next job.

• Cancelling works across processes: phomemo cancel stops a print an AI agent started.

• Only one job talks to a printer at a time. The others wait as queued.

• Job statuses:

  • done: the printer confirmed every card printed.

  • unconfirmed: all data was sent but the printer never confirmed. Check the output; a low battery is the usual cause.

  • failed, cancelled.

Job history lives in ~/.local/state/phomemo/jobs (override with PHOMEMO_STATE).

MCP server (Claude and other agents)

phomemo mcp                          # stdio
phomemo mcp --http 127.0.0.1:8765    # streamable HTTP at /mcp

Tools: print_cards, preview_cards (returns images, so the agent can check the layout first), print_picture, printer_status, list_print_jobs, cancel_print, reprint, list_printers. The print tools wait up to 15 seconds. A longer print keeps running in the background and the tool returns its job id.

Claude Code

claude mcp add phomemo -s user -- phomemo mcp

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "phomemo": { "command": "phomemo", "args": ["mcp"] } } }

Use the full path from which phomemo if the app can't find the command.

Configuration

Optional. Without a config file you get one printer, m02pro, found automatically. phomemo config shows where the file goes, with an example:

default = "desk"

[printers.desk]
model = "m02pro"
# address = "…"    # from `phomemo scan`; skips discovery, picks one of several printers
# feed = 3         # blank lines after each card

Driver options are listed in src/phomemo/drivers/m02.py.

Troubleshooting

• "not found over Bluetooth": turn the printer on and close the Phomemo app. On macOS, the app running phomemo (Terminal, iTerm, Claude…) needs Bluetooth access under System Settings → Privacy & Security → Bluetooth.

• The light blinks fast: the paper is out, the printer is too hot, or the battery is low. phomemo status tells you which.

• It won't charge from a USB-C charger: use a 5V USB-A charger with an A-to-C cable. Some USB-C chargers never switch on power for this printer. Phomemo warns that chargers above 5V can damage it.

• Photos look muddy: pictures are contrast-stretched and brightened before dithering, but thermal paper suits strong contrast. Bold images print best.

Thermal paper

Most thermal paper contains BPA or BPS, and both are absorbed through the skin. "BPA-free" usually means BPS. If you'll handle the prints a lot, look for phenol-free paper.

How it works

The protocol was reverse-engineered by others (see Credits). What this project verified on a real M02 Pro, including the print-complete signal and the status replies, is in PROTOCOL.md.

src/phomemo/
  cards.py        Markdown → cards
  render.py       cards / pictures → grayscale images at printer width
  drivers/m02.py  M02 family: raster encoding, Bluetooth transport, status
  jobs.py         job records, per-printer queue, cancel, reprint
  api.py          shared by the CLI and the MCP server
  cli.py          `phomemo`
  mcp_server.py   `phomemo mcp`

Contributing

Issues and pull requests are welcome, especially reports from M02S, M02 and T02 owners (does printing work, and does phomemo status answer?).

uv sync
uv run pytest

⚠️ Don't probe unknown 1F 11 NN commands. Sweeping opcodes above 0x14 bricked an M02X. Stick to documented commands.

Credits

The protocol knowledge comes from vivier/phomemo-tools, ryo-endo/phomemo-printer, theacodes/phomemo_m02s and sgrankin/phomemo. This project re-implements it and contains no code from those projects.

Not affiliated with Phomemo.

License

MIT