Skip to main content
Glama
supvan-e11

supvan-e11

by marco308

supvan-e11-mcp

CI codecov

Print labels on a SUPVAN E11 Bluetooth label maker without the phone app: from Claude on a Mac (local MCP server), from the command line, or from a small label service on a home server (REST API + remote MCP) that other apps and agents can call.

Not affiliated with SUPVAN. It works with the one E11 I own; the protocol code covers the E-series (E10/E11/E12/E16) but only the E11 is tested.

Label service

A container that runs next to a Bluetooth adapter and prints for any client with a token. It reaches the printer through the host's own adapter plus any ESPHome Bluetooth proxies listed in SUPVAN_PROXIES, using whichever hears the printer best. Every endpoint except /api/health needs Authorization: Bearer <client token>.

Security

The service is built to be reachable from the internet behind a reverse proxy (mine is Cloudflare → Traefik → nginx → service), so:

  • One token per client app (claude-code, meals-app, …), managed on the host with deploy/tokens.py add|list|revoke <name>. Only SHA-256 hashes are stored (deploy/secrets/clients.json, git-ignored); changes apply without a restart. Every request is logged with the client name and IP.

  • Real client IPs: behind Cloudflare the proxy only sees Cloudflare edges, so the service uses the CF-Connecting-IP header, trusted only when the hop the proxy saw is a published Cloudflare range (security.py).

  • Rate limits (in memory): 10 bad tokens from one IP in 10 min bans that IP for an hour; 120 requests per client per minute; 60 labels per client per 10 minutes and 500 per day (copies count); /api/health 30 per IP per minute. Over a limit returns 429 with Retry-After.

  • Size limits: labels are 8–300 mm long with at most 300 characters of text, so a request can't make the service draw a huge image.

  • What it doesn't do: a caller who reaches the container's port directly, skipping the proxy, can forge the forwarding headers and dodge the per-IP ban (it still needs a valid token). Keep that port on a trusted network.

# Freezer label: dish, frozen (default today), qr; use_by and portions only if given
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"template":"freezer","fields":{"dish":"Chilli con carne","portions":2}}' \
  https://labels.example.com/api/labels/print

# Any text label; /api/labels/preview takes the same JSON and returns a PNG
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"text":"Spices\nTop shelf","border":true}' https://labels.example.com/api/labels/preview -o p.png

Endpoint

GET /api/health

no auth; liveness only

GET /api/radios

which radios currently see a printer

GET /api/status

model, tape, labels left, problems

POST /api/labels/preview

label JSON → PNG

POST /api/labels/print

label JSON (+ copies, density) → {"ok": true}

POST /api/feed, POST /api/release

feed a label; drop Bluetooth

/mcp

MCP over streamable HTTP, same tools as below

Errors come back as {"ok": false, "error": "..."}: 400 for a bad request, 503 when the printer can't be reached (usually switched off; it powers itself down after a while and can't be woken over Bluetooth).

Deploying

CI builds ghcr.io/marco308/supvan-e11-mcp:<sha> on every push to main. On the Linux machine with the Bluetooth adapter:

git clone https://github.com/marco308/supvan-e11-mcp && cd supvan-e11-mcp
cp deploy/.env.example deploy/.env    # set LABEL_HOST, and SUPVAN_PROXIES if any
deploy/tokens.py add my-first-client  # prints the token once
deploy/deploy.sh

deploy/ is how I run it, on Docker Swarm with Traefik; treat it as an example. The service itself is a Compose container, not a Swarm service, because reaching BlueZ over D-Bus needs apparmor:unconfined, which Swarm can't set. Traefik only routes to Swarm services, so deploy/stack.yml runs a small nginx front door for LABEL_HOST. Without Swarm, docker compose -f deploy/compose.yml up -d alone gives you the service on port 8799; put your own HTTPS proxy in front of it.

Adding a room: flash an ESP32 with ESPHome's Bluetooth proxy firmware (bluetooth_proxy: active: true), then add host|api_encryption_key to SUPVAN_PROXIES in deploy/.env and re-run deploy/deploy.sh.

Related MCP server: labelprint

Mac setup (local MCP)

Claude ──MCP──▶ server.py ──Unix socket──▶ Label Printer Bridge.app ──BLE──▶ E11
                (draws labels)             (daemon.py, owns Bluetooth)

macOS kills any process that uses Bluetooth unless the app responsible for it declares NSBluetoothAlwaysUsageDescription. Claude Code and plain python don't, so the Bluetooth side runs in a tiny app bundle of its own. The MCP server and CLI start it with open when needed. It drops the printer after two idle minutes so the phone app can connect again.

uv sync
scripts/make_app.sh            # builds ~/Applications/Label Printer Bridge.app
claude mcp add --scope user supvan-e11 -- uv --directory "$PWD" run supvan-e11-mcp

Rebuild the app only if you move the repo (it points at this checkout's .venv). The bridge logs to ~/Library/Logs/label-printer-bridge.log. Set SUPVAN_DEBUG=1 when the bridge first starts to log every frame.

MCP tools

Tool

What it does

printer_status

Model, loaded tape (width, label length, labels left), problems

preview_label

Picture of a text label and a preview_id, nothing printed

preview_freezer_label

The same for the freezer template

print_label

Print a preview by its preview_id (copies, density)

feed_tape

Feed one blank label

release_printer

Drop Bluetooth so the phone app can connect

Labels take text (\n for a second line), length_mm (defaults to the loaded label), font (sans-bold, sans, condensed-bold, condensed, serif, mono; bundled DejaVu), size, align, qr, border and invert.

Printing needs a preview. print_label takes the preview_id a preview returned and prints exactly that picture, so an agent can't print a label nobody was shown. Each preview prints once (copies sets how many) and lasts 10 minutes, and only the client that made it can print it, so a retry or a second turn after a dropped link can't print the same label twice. This is MCP only: the REST API's POST /api/labels/print still prints in one call, because an app's print button is already a person choosing one label.

CLI

uv run supvan-e11 status
uv run supvan-e11 print 'Flour\nopened 1 Oct' --qr https://example.com --preview /tmp/p.png --dry-run
uv run supvan-e11 print "Spices" --border

Hardware facts (my unit)

  • Advertises under a name starting T0 followed by its serial; reports model G15, firmware 1.

  • Bluetooth service fee7, one characteristic fec1 for both notify and write (write without response), written in 128-byte chunks.

  • Print head 96 dots (12 mm) at 8 dots/mm. Tape: 12 × 40 mm die-cut, 3 mm gap.

  • Verified 2026-10-01 with a bordered test label: image row 0 / LSB-first is correct (not mirrored or flipped), the full 96 × 320 dot border prints, and density 4 is crisp. Placement along the label is within ~0.5 mm of centre.

Credits

The protocol comes from heeen/supvan-cups (MIT), via the E11 work in efcroasdell/supvan-cups and Curetix/label-printer. protocol.py mirrors the Rust function names.

Licence

MIT, see LICENSE. It carries Florian Hänel's copyright notice too, because protocol.py and printer.py are ported from his MIT-licensed supvan-cups. The bundled DejaVu fonts have their own licence (src/supvan_e11_mcp/fonts/DejaVu-LICENSE).

Available Tools

6 tools
feed_tapeB

Feed the tape on by one label without printing.

Inputs: no named parameters. Returns: result

preview_freezer_labelA

Picture of a freezer label, and a preview_id to print it with print_label: dish name large, then the date it was frozen. frozen defaults to today; use_by and portions are added only when given (ISO dates, e.g. 2026-10-01). qr: optional text/URL for a QR code at the left end.

Inputs: dish (required), qr, frozen, use_by, +1 more.

preview_labelA

Draw a text label and return a picture of it, and a preview_id, without printing.

text: label text; use \n for a new line (two lines fit comfortably, three is tiny). length_mm: label length along the tape; default is the loaded die-cut label length. font: sans-bold (default), sans, condensed-bold, condensed, serif or mono. size: font height in dots (8 dots per mm, the tape is 96 dots high); default fits the text. align: left, center or right. qr: if set, a QR code holding this text/URL goes at the left end. border: draw a rounded border. invert: white text on black.

Inputs: text (required), qr, font, size, +4 more.

printer_statusA

Connect to the label printer and report model, loaded tape (width, label length, labels remaining) and any problem such as the cover being open or the tape running out.

Inputs: no named parameters.

release_printerA

Drop the Bluetooth connection so the phone app can connect. The connection comes back by itself next time, and is also dropped after two idle minutes.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    The preview/print split is clear: preview_label and preview_freezer_label generate a preview_id, and print_label consumes it. The only mild overlap is between the two preview tools, but their descriptions make the free-text vs freezer-template distinction obvious.

    Naming Consistency4/5

    All names are snake_case and nearly all follow a verb_noun pattern (preview_label, print_label, feed_tape, release_printer). printer_status is noun-first rather than the verb_noun style, a minor deviation but still readable and predictable.

    Tool Count5/5

    Six tools is well-scoped for a label printer: status, two previews, print, feed, and connection release. Each tool covers a distinct step in the workflow with no filler.

    Completeness4/5

    The lifecycle from checking status through preview, print, feed, and releasing the connection is covered. Minor gaps exist, such as no cancel/abort of a print or explicit printer configuration tool, but the density parameter inside print_label partly covers that.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables printing PNG labels to a nearby thermal label printer over local serial or Bluetooth, with tools for rendering previews, checking printer status, and printing with confirmation.
      5
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables printing labels on Brother P-touch tape printers via MCP, allowing natural language requests to create, preview, and print labels.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A stdio MCP server that lets AI clients drive an unofficial Paperang P1 thermal printer service, exposing 13 tools for status, device scanning, connection, printing, configuration and job management. It enables text/image output and queue control through natural-language requests without touching the printer's protocol directly.
      2
      MIT