niimbot-mcp

An MCP server + toolset to print to NIIMBOT BLE label printers directly — no vendor app, no cloud. The MCP provides the toolset and guidance; the calling agent composes what to print (text / QR / image).

Reverse-engineered from the community protocol work (niimbluelib, niimprint) and confirmed live against a NIIMBOT B1.

Hardware confirmed

• NIIMBOT B1, 203 dpi, 50 mm print head (384 px wide).

• BLE quirk: despite advertising the ISSC 49535343-… UART service, the B1 only replies on characteristic bef8d6c9-9c21-4c9e-b632-bd58c1009f9f. Both write and notify go through that one characteristic.

Related MCP server: print-blocks

Protocol (packet framing)

55 55 | TYPE | LEN | DATA… | XOR_CHECKSUM | AA AA
checksum = TYPE ^ LEN ^ (each data byte)

Working print flow (B1): SET_DENSITY 0x21 → SET_LABEL_TYPE 0x23 → START_PRINT 0x01 (2-byte page count) → START_PAGE 0x03 → SET_DIMENSION 0x13 (6-byte: rows, cols, copies) → bitmap rows 0x85 (pos:2 | black_count:3 | repeats:1 | row_data) → END_PAGE 0xE3 → poll GET_PRINT_STATUS 0xA3 → END_PRINT 0xF3.

The bare 1-byte START_PRINT and the 4-byte SET_DIMENSION produce blank output or many copies on the B1 — use the forms above.

⚠️ BLE flow control (the big one)

Stream every packet with write-WITH-response (write_gatt_char(..., response=True)). With response=False, the BLE stack silently drops packets under backpressure:

• ~half the rows dropped → the page clips mid-way (~120px on a 240px label), which looks exactly like a wrong label-size / geometry bug (it is not).

• all rows dropped → nothing feeds, which looks like a transient BLE drop or a dead link (it is not).

If a print clips or fails to feed, check this FIRST — before geometry, label size, or connection theories. Also: do not send ALLOW_PRINT_CLEAR (0x20) — the B1 does not support it and it silently breaks every subsequent print.

Safe margin

Content is inset by a configurable safe_margin_mm (default 3mm) on all sides so text/QR captions don't print off the label edge. check_fit accounts for it.

Install

python3 -m venv .venv
./.venv/bin/pip install -U bleak pillow qrcode "mcp[cli]"

macOS: grant your terminal Bluetooth permission (System Settings → Privacy & Security → Bluetooth) on first run.

MCP tools

Orientation

• horizontal (default): text reads left-to-right across the label width.

• vertical: rotated 90°, for long thin labels.

QR and images auto-fit the label either way. Config persists to ~/.config/niimbot-mcp/config.json.

Register with Kiro Crew

Add to ~/.kiro/agents/kirocrew.json under mcpServers:

"niimbot": {
  "command": "/Users/italo/Code/niimbot-mcp/.venv/bin/python",
  "args": ["/Users/italo/Code/niimbot-mcp/server.py"]
}

Layout

niimbot/
  packet.py   # 55 55…AA AA framing + codec
  client.py   # async BLE client + print flow
  config.py   # persisted paper/printer settings
  render.py   # text/QR/image → oriented, label-sized 1-bit bitmap
server.py     # MCP server (toolset + guide)
scan.py probe.py diag.py  # discovery utilities used during bring-up