# Printercow

> Printercow is a Wi-Fi dongle with a USB host port that connects a USB device, such as a receipt printer, label printer or scale, to AI assistants over the Model Context Protocol (MCP) and to your own code over a REST API. An AI such as Claude works out how to drive the device once and saves what works as named actions. After the owner approves them, those actions run as MCP tools and REST API endpoints, with no AI needed.

Status as of 2026-11-04: public beta. Setup, online status, USB plug-in events, signed firmware updates, webhooks, the MCP server, recipe review, a shared recipe registry, label templates, print jobs and the REST API work. Prints have run on real printers: an 80 mm ESC/POS receipt printer and a TSPL label printer. Receipts need no recipe: once the owner sets the paper width on the dongle page, the server draws a receipt or a saved template and prints it. The first Rev C dongles are built and tested on real printers, and not for sale yet; until they are, anyone can flash the same firmware onto a Seeed XIAO ESP32-S3 from the browser (a powered USB-C OTG adapter supplies the device; the XIAO has no current limit or ESD protection). Prints run from the cloud; the dongle runs the USB steps it is sent and has no offline mode. Recipe triggers are planned.

**How it works**

1. The dongle plugs into the device and joins 2.4 GHz Wi-Fi, set up over Bluetooth from a browser. No computer, driver or app sits next to the device.
2. An MCP client (Claude Code, claude.ai, ChatGPT, Cursor or any client with remote HTTP MCP) connects to the Printercow MCP server at `https://milk.printercow.com/mcp`, with OAuth sign-in or an API token sent as `Authorization: Bearer <token>`.
3. The AI explores with tools such as `list_dongles`, `read_device_guide`, `describe_device`, `usb_transfer` and `ask_operator`, draws labels and receipts on the server with `render_preview` and `print_label`, and saves designs with `save_label_template`.
4. When something works, it proposes a recipe: named actions with typed parameters and a check (device status reply or a sensor on the dongle) that confirms each action worked. The owner approves it on the dashboard. `find_recipe` also offers recipes other workspaces shared for the same USB ID.
5. Each approved action becomes an MCP tool named `<action>_<vid>_<pid>`, such as `print_0416_5011`, and a REST endpoint. Saved label templates print by name with typed parameters, from an AI or from code.
6. Every print is a print job in its dongle's queue: it waits its turn instead of failing as busy, an `Idempotency-Key` keeps a retry from printing twice, and `print.job.*` webhooks say how it ended. The first big print on a new printer prints only its top; after the owner confirms it on the dongle page, the job prints whole by itself.

**REST API**

- Reference: https://milk.printercow.com/docs (also https://printercow.com/docs). Machine-readable OpenAPI 3.1 document: https://milk.printercow.com/api/v1/openapi.json
- Authenticate with an API token from the dashboard's Connect page: `Authorization: Bearer pc_live_...`.
- `GET /api/v1/dongles`: the dongles the token reaches, what is plugged in, the recipe's actions and the templates that print there.
- `POST /api/v1/print-jobs` with `{ "dongleId", "template", "params" }` and an `Idempotency-Key` header: queues a print and answers 202 with the job; it waits out an offline dongle for up to 10 minutes by default (`expiresInSeconds`, up to 24 h).
- `GET /api/v1/print-jobs/{id}`: the job's status: `queued`, `printing`, `waiting_for_operator`, then `completed`, `failed`, `canceled` or `expired`.
- `POST /api/v1/label-templates/{name}/print` and `POST /api/v1/devices/{dongleId}/actions/{action}`: print and wait for the result in one call. The response carries the USB results, `check.outcome` (`passed`, `failed` or `unverifiable`) and the job.
- docs.printercow.com describes the previous Printercow (api.printercow.com, `prt_` and `tpl_` ids), not this API.

**Limits**

- Full-speed USB only (12 Mbit/s), one device per dongle, no hubs. Not for webcams, audio or storage.
- Not a print server and not USB over IP: it does not add a printer to Windows or macOS.
- Every action goes through the cloud; no offline operation. A print job waits for an offline dongle until it expires.
- Vendor-specific USB requests and firmware-update interfaces are blocked until the dongle's owner allows them. 60 USB commands per minute per dongle. Every transfer is logged.

## Pages

- [Home](/): what Printercow is, how a device becomes an API, hardware, status and FAQ
- [API reference](/docs): every REST call with its fields and answers, from the API's own OpenAPI document
- [My 80 mm receipt printer, driven by ChatGPT](/guides/thermal-receipt-printer): Sebastian Klein's own setup, the prompts he typed, a receipt saved as a template and printed from code
- [A label rebuilt from a photo, on my thermal label printer](/guides/thermal-label-printer): a MUNBYN 4×6 TSPL printer, a coupon rebuilt by Claude from a photo as a template with a QR code
- [Connect a receipt printer to Claude](/use-cases/claude-receipt-printer): MCP setup in Claude Code and claude.ai, what Claude can do, limits
- [A REST API for your kitchen printer](/use-cases/kitchen-printer-api): the print action over HTTPS, response checks, offline behaviour
- [A USB receipt printer with no computer attached](/use-cases/print-without-computer): how the dongle replaces the PC, compared with a print server
- [Build a dongle from a XIAO ESP32-S3](/diy): parts, the five steps, differences from the dongle, troubleshooting
- [Flash a XIAO ESP32-S3](/flash): install the firmware from Chrome or Edge, or download the files for esptool
- [Create a workspace](/signup): sign up, then connect an AI client from the Connect page

## Optional

- [Guides](/guides)
- [Use cases](/use-cases)
- [How it works](/#how)
- [Hardware](/#hardware)
- [Status](/#status)
- [FAQ](/#faq)