Open Xprinter MCP

Let AI clients prepare, preview and print labels on an Xprinter XP-330B using the Model Context Protocol. Local clients use stdio; remote clients use SSH or OAuth-authenticated HTTPS. Windows, Linux and macOS clients use the same API. Host MCP on the printer Mac, or run the ready Docker image anywhere and connect to that Mac over SSH. The USB driver/native renderer stay on the Mac.

Downloads · Docker quick start · Русский · 简体中文 · Remote access · Security · Contribute

Ready Docker image

ghcr.io/ismoil-nosr/xprinter-mcp:0.2.1 supports Intel/AMD and ARM. Download the release's Docker quick-start ZIP, set the Mac SSH account/key/verified host key in docker.env, then:

docker compose --env-file docker.env pull xprinter
docker compose --env-file docker.env run --rm -T xprinter doctor
docker compose --env-file docker.env run --rm -T xprinter

The last command starts MCP stdio; the client JSON template connects an AI app. Node and MCP dependencies are already in the image: the printer Mac needs only Open Xprinter 0.3.1+ and SSH, with its project queue configured. Printing starts disabled. The named state volume preserves retry receipts when containers are recreated; enabling printing without it is refused. An optional Compose HTTP profile retains mandatory OAuth and publishes only to host loopback. English · Русский · 简体中文.

Related MCP server: printagent

Install on the printer Mac

1. Install Open Xprinter 0.3.1 or newer, connect USB, configure the XP330B_OpenSource queue and verify one label in the native app. The driver package is currently unsigned by Apple; follow its installation guide. Use the actual label dimensions and gap.

2. Install Node.js 24 LTS or newer on the server Mac. The native app/driver themselves do not need Node.

3. Download the .tgz and SHA256SUMS.txt from this repository's release, verify the archive with shasum -a 256, then install the local archive:

npm install --global ./ismoil-nosr-xprinter-mcp-0.2.1.tgz
xprinter-mcp doctor

doctor checks the native renderer and printer queue without moving paper. Queue readiness does not prove that the physical USB device is connected. The runtime archive includes compiled JavaScript and a dependency shrinkwrap; npm fetches the pinned dependencies. No npm registry publication is required; the release archive is the distribution. Do not use npx @ismoil-nosr/xprinter-mcp until the package is actually published to npm.

For development:

git clone https://github.com/ismoil-nosr/xprinter-mcp.git
cd xprinter-mcp
npm ci --ignore-scripts
npm run build
node dist/cli.js doctor

Connect locally

Use your MCP client's server configuration (the outer configuration shape varies by client):

{
  "mcpServers": {
    "xprinter": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/xprinter-mcp/dist/cli.js", "stdio"],
      "env": {
        "XPRINTER_ALLOW_PRINT": "1",
        "XPRINTER_LANGUAGE": "en"
      }
    }
  }
}

Find the Node executable with command -v node; use absolute paths so GUI clients do not depend on shell startup files. With a global installation you can instead use the absolute path returned by command -v xprinter-mcp as command, with args: ["stdio"], provided the GUI client's PATH also includes Node. Examples in examples include stdio and SSH.

Physical printing is disabled by default. Omit XPRINTER_ALLOW_PRINT=1 for preparation/preview only. Enabling it grants the MCP client the ability to spend paper; choose trusted clients and configure their own tool approval policy. confirmed: true and tool annotations help avoid accidents but are not an independent human approval mechanism. Read the security boundary.

Tool titles/descriptions support XPRINTER_LANGUAGE=en, ru or zh-Hans. Tool names, JSON fields, dimensions and machine errors stay stable. Labels can contain Chinese/Russian text; Code 128 needs printable ASCII, while QR supports Unicode.

xprinter-mcp config prints client JSON with the actual absolute Node/module paths. It starts with printing disabled unless you explicitly set XPRINTER_ALLOW_PRINT=1 when generating it. Copy that configuration into your client's MCP settings.

Printing workflow

1. Read printer_capabilities and printer_status.

2. Confirm the stock actually loaded: width across the roll, height along feed, gap/mark height and stock type. The initial profile is 58×40 mm, 2 mm gap, darkness 7.

3. Call prepare_labels or prepare_pdf. It returns an expiring artifact ID, physical settings, page count and a PNG of page 1 only. Preparation does not move paper.

4. Review the preview and batch contents; obtain the user's explicit print instruction. Send print_labels with confirmed: true and a new UUID idempotencyKey for this intended print.

5. On a network retry, reuse exactly that UUID and the same artifact/copies. Read job_status. An uncertain receipt requires inspection of the Mac queue and paper; never automatically submit another key.

Example preparation:

{
  "profile": {"widthMm": 58, "heightMm": 40, "stock": "gap", "gapMm": 2, "darkness": 7},
  "labels": [{"kind": "qr", "title": "商品 · Товар", "code": "TEST-123", "footer": "¥25", "quantity": 1}]
}

quantity expands each record into pages; copies repeats the resulting document. The limit applies to pages × copies. Supported input is Code 128, QR, text or a base64 PDF; arbitrary paths, URLs, raw printer commands and shell commands are never tool inputs. PDF fitting preserves aspect ratio and does not split A4 sheets containing multiple labels.

Resources expose capabilities and xprinter://labels/{artifactId} PDFs for the authenticated owner. The label_printing_workflow prompt explains the preparation/confirmation flow. CUPS “completed” does not verify label alignment, paper movement or scanner readability. Cancellation cannot undo paper already printed.

Remote clients and platform support

Windows and Linux clients do not need a macOS driver or a different MCP API. They connect to a native server Mac via SSH/HTTPS, or run the MCP server in Docker using the SSH printer backend. The printer Mac needs the native driver and renderer; only native MCP hosting also needs Node there. Direct USB hosting on Windows/Linux is not implemented in this release; the backend interfaces are separate from the MCP core so such backends can be added with their own validation. See architecture.

Start with SSH using key authentication; it needs no public HTTP service or OAuth provider. Native HTTP mode defaults to 127.0.0.1; the Docker Compose HTTP profile listens inside the container and publishes only to host loopback. Both require an operator-configured HTTPS reverse proxy plus an OAuth provider issuing audience-bound JWT access tokens. There is no anonymous HTTP mode. REMOTE.md covers setup and OAuth configuration covers the provider contract.

The official TypeScript SDK v2 serving APIs support MCP 2026-07-28 plus the 2025 compatibility handshake on the same stdio/Streamable HTTP endpoints. Legacy HTTP+SSE transport is not provided. Official SDK migration guide.

Configuration and limits

MCP limits: width 20–76 mm, feed height 10–200 mm, 50 records/100 pages, PDF input 2 MiB/100 pages, rendered PDF 6 MiB, 40 million batch pixels, 2 concurrent renders. Prepared data expires after 15 minutes, with a 64 MiB/128-artifact shared storage quota. Receipts remain 30 days; even uncertain/cancelled jobs count conservatively toward the hourly paper budget. Retrying a receipt after 30 days is outside the deduplication window. State is local SQLite through Node's built-in API; Node 24 may emit an experimental SQLite warning on stderr, which does not affect MCP stdout.

Keep the server Mac awake, its USB connection available and label stock unchanged while accepting remote jobs. Other native apps share the physical queue and are outside MCP authorization/budgets. The project currently addresses one configured XP-330B queue per Mac.

Use one authoritative deployment/state volume per printer. Different native/Docker installations with different state paths have separate budgets. A state directory is bound to its backend target; preserving receipts across a container upgrade is required, and changing the target silently is refused.

Test, package and uninstall

npm ci --ignore-scripts
npm test
npm pack

Core tests run on Linux, Windows and macOS with synthetic printer adapters. Real native integration tests require a built/installed 0.3.1+ app and XPRINTER_RENDERER set to its executable. They consume no paper. CI also validates real rendering on macOS 14 ARM, macOS 15 Intel and macOS 26 ARM. See validation and its limits.

To remove a global install: stop its MCP clients/service, run npm uninstall --global @ismoil-nosr/xprinter-mcp, and remove its client configuration. The native app/driver and private state are retained. If you choose to erase the state directory after stopping all server processes, you also erase retry receipts; inspect pending/uncertain jobs first. Never keep a state database on a network filesystem or share one HTTP service through untrusted local accounts.

MIT, copyright Ismoil Nosr. Independent of Xprinter; no vendor binaries, PPDs or SDK source are bundled.

Security maintenance includes npm audit, CodeQL, PR dependency review, weekly Dependabot/image scans and digest-based image promotion after both architectures pass. Policy and private reporting. Upgrade the printer Mac to Open Xprinter 0.3.1+ for the independent renderer deadline.