This server lets you print markdown content to a POS (point-of-sale) receipt printer via a CUPS URI, using a two-step confirmation flow.
Preview before printing: Call the print tool with mode=preview to get a preview snippet, line count, and a confirmation token — without sending anything to the printer yet. Receive an excessive length warning if the markdown exceeds 80 lines.
Confirm and print: Call the print tool again with mode=confirm and the confirmationToken to actually send the job to the printer.
Target specific printers: Provide a CUPS/IPP printer URI, or omit it if a default is configured via the PRINTER_URI environment variable.
Control print options: Optionally specify the number of copies and a timeout (in milliseconds) for the print job.
Receive job metadata: Upon successful confirmation, get details like the printer URI, duration, timestamp, and an optional job ID.
Error handling: Returns specific error codes for validation, printer, or timeout issues.
Remote access: Can run as an HTTP server with an authentication token for remote clients, plus an unauthenticated health check endpoint.
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., "@@bestimmaa/posprint-mcp print receipt for order #123"
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.
MCP server for POS printer receipts using @bestimmaa/posprint.
The tool is intentionally named print so clients can map natural user phrasing such as "print receipt", "hard copy", or "print this out" to the same operation.
Node.js 20+
A printer reachable via a CUPS URI supported by @bestimmaa/posprint
Related MCP server: Yamato Printer MCP Server
Add this to your MCP client config. No separate installation step is required — npx fetches the package on first run.
{
"mcpServers": {
"posprint": {
"command": "npx",
"args": ["-y", "@bestimmaa/posprint-mcp"]
}
}
}npm install -g @bestimmaa/posprint-mcpAfter global installation, you can use the shorter form in your MCP client config:
{
"mcpServers": {
"posprint": {
"command": "posprint-mcp"
}
}
}For clients that can only talk to a remote MCP server (e.g. Notion custom agents), run posprint-mcp in a Docker container over HTTP instead of stdio. The image defaults to MCP_TRANSPORT=http.
.envCopy .env.example to .env and fill in your values — .env is gitignored, so real tokens/URIs never get committed.
cp .env.example .env
# edit .env: set POSPRINT_AUTH_TOKEN (e.g. `openssl rand -hex 32`) and PRINTER_URI
docker compose up -d --builddocker-compose.yml reads .env automatically (both for the container's env vars and the host port mapping). To run without Compose, pass the same file to docker run directly:
docker build -t posprint-mcp .
docker run -d --name posprint-mcp -p 3000:3000 --env-file .env posprint-mcpThe server listens on POST /mcp (MCP Streamable HTTP transport, stateless) and GET /healthz (unauthenticated health check). It refuses to start if POSPRINT_AUTH_TOKEN is unset, since an unauthenticated remote endpoint would let anyone on the network print to your printer.
Point your remote MCP client at http://<host>:3000/mcp with header-based auth:
Authorization: Bearer <POSPRINT_AUTH_TOKEN>Note: the container needs network access to your printer's CUPS/IPP endpoint (typically on your LAN), so run it on a network that can reach it (e.g. --network host, or a bridge network with routing to the printer's subnet).
.local (mDNS) hostnames will not resolve inside the container — most base images (including this one) have no mDNS support, so a PRINTER_URI like ipp://myprinter.local:631/... will fail to connect. Use one of:
The printer's static/reserved IP address, or
A regular DNS name if your router provides one (e.g. many Fritz!Box routers also expose LAN devices as <name>.fritz.box, which resolves via normal DNS and works fine in containers).
Variable | Applies to | Description |
| both |
|
|
| Port to listen on. Defaults to |
|
| Bearer token required on every |
| both | Default CUPS printer URI. When set, the |
npm install
npm run build
npm testRun the local server from source:
npm run devRun the built server:
npm startprintInput:
printerUri?: string (optional if the server has a default configured via the PRINTER_URI environment variable)
markdown: string
mode: "preview" | "confirm"
confirmationToken?: string (required when mode="confirm")
options?: { copies?: number; timeoutMs?: number }
Call print with mode: "preview".
Show the returned snippet to the user and ask for confirmation.
Call print again with mode: "confirm" and the returned confirmationToken.
Preview response includes:
requiresConfirmation: true
confirmationToken
preview.lineCount
preview.snippet
preview.excessiveLengthWarning (present when markdown is more than 80 lines)
Confirm response shape:
{ "ok": true, "meta": { "printerUri": "...", "durationMs": 20, "printedAt": "...", "jobId": "optional" } }Error codes:
VALIDATION_ERROR
PRINTER_ERROR
TIMEOUT
Print markdown content to a POS printer via CUPS URI. Use this when the user asks to print, print a receipt, make a hard copy, or print something out. Call with mode=preview first, then call again with mode=confirm and confirmationToken.
| Name | Required | Description | Default |
|---|---|---|---|
| printerUri | Yes | ||
| markdown | Yes | ||
| mode | Yes | ||
| confirmationToken | No | ||
| options | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the two-step process (preview then confirm), but does not explain what happens during each mode (e.g., preview returns estimated cost or content preview, confirm triggers actual printing). More detail on side effects or irreversible actions would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: one for purpose, one for usage context, one for the workflow. No redundant information. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, nested options, and a two-mode workflow. The description covers the workflow and basic usage but omits parameter semantics and does not mention return values or error handling. Given the complexity, more detail is needed for a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must explain parameters. It only contextualizes 'mode' and 'confirmationToken' via the workflow. The other parameters (printerUri, markdown, options) receive no explanation. For example, 'printerUri' should be a CUPS URI, 'markdown' is the content to print, and 'options' includes copies and timeout. This gap makes it hard for an agent to use correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states printing markdown to a POS printer via CUPS URI. It's specific about the action and resource. No sibling tools exist, so differentiation is not required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this tool (user asks to print, make a hard copy, etc.) and provides a precise workflow: call with mode=preview first, then mode=confirm with a token. This is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0printScored across 1 tool
With only one tool, there is no risk of confusion or overlap between tools.
A single tool named 'print' is perfectly consistent with itself.
A single tool for a POS printing server feels too minimal; typically one would expect additional utilities like printer listing or status checks.
The print tool covers only the core print action via two modes, missing obvious features like printer discovery, job management, or error handling.
MCP server for Probo print-on-demand — search products, configure orders, track shipments.
A paid remote MCP for hosted MCP server, built to return verdicts, receipts, usage logs, and audit-r
HTML-to-PDF MCP server — render pixel-faithful PDFs from HTML.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
