supvan-e11
Enables printing labels on SUPVAN E-series Bluetooth label makers over BLE, including printer status, label previews, printing, feeding tape, and releasing the Bluetooth connection.
Allows the label service to use ESPHome Bluetooth proxies (ESP32 devices) as additional radios to reach and print to the label printer, selecting whichever proxy hears the printer best.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@supvan-e11 print a freezer label for chilli con carne, 2 portions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
supvan-e11-mcp
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 withdeploy/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-IPheader, 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/health30 per IP per minute. Over a limit returns 429 withRetry-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.pngEndpoint | |
| no auth; liveness only |
| which radios currently see a printer |
| model, tape, labels left, problems |
| label JSON → PNG |
| label JSON (+ |
| feed a label; drop Bluetooth |
| 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.shdeploy/ 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-mcpRebuild 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 |
| Model, loaded tape (width, label length, labels left), problems |
| Picture of a text label and a |
| The same for the freezer template |
| Print a preview by its |
| Feed one blank label |
| 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" --borderHardware facts (my unit)
Advertises under a name starting
T0followed by its serial; reports modelG15, firmware 1.Bluetooth service
fee7, one characteristicfec1for 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 toolsfeed_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.
print_labelA
Print a label the user has seen: exactly the picture from preview_label or preview_freezer_label. Show the user the preview and print only once they're happy.
preview_id: from the preview, made in the last 10 minutes. Each preview prints once; preview again to print it again. copies: how many to print (1-20). density: darkness, 1-15 (default 4); raise it if the print is faint.
Inputs: preview_id (required), copies, density. Returns: result
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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables Claude or any MCP client to design and print text and images to Bluetooth thermal label printers, including scanning, configuring, and managing multiple printers.12-
- AlicenseAqualityDmaintenanceEnables 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.52MIT
- AlicenseNot gradedqualityBmaintenanceEnables printing labels on Brother P-touch tape printers via MCP, allowing natural language requests to create, preview, and print labels.MIT
- AlicenseNot gradedqualityBmaintenanceA 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.2MIT