@inkrelay/mcp

MCP server for the InkRelay printing API. It lets an AI assistant list your printers and print PDFs, ZPL labels and ESC/POS receipts on printers attached to Windows, macOS and Linux computers.

Works with Claude Code, Claude Desktop, Cursor, VS Code (GitHub Copilot), OpenAI Codex, Windsurf and any client that speaks the Model Context Protocol over stdio.

Get a key

Sign in at app.inkrelay.app, open API keys and create one. Start with a test key (ir_test_...): it only reaches four virtual printers (Test A4 Laser, Test Letter Color, Test Receipt 80mm, Test Label 4x6), finishes jobs in about 3 seconds and costs nothing. A live key (ir_live_...) prints on paper.

Add it to your client

Claude Code

claude mcp add-json inkrelay '{"command":"npx","args":["-y","@inkrelay/mcp"],"env":{"INKRELAY_API_KEY":"ir_test_your_key"}}'

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "inkrelay": {
      "command": "npx",
      "args": ["-y", "@inkrelay/mcp"],
      "env": { "INKRELAY_API_KEY": "ir_test_your_key" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "inputs": [{ "type": "promptString", "id": "inkrelay-key", "description": "InkRelay API key", "password": true }],
  "servers": {
    "inkrelay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@inkrelay/mcp"],
      "env": { "INKRELAY_API_KEY": "${input:inkrelay-key}" }
    }
  }
}

OpenAI Codex (~/.codex/config.toml)

[mcp_servers.inkrelay]
command = "npx"
args = ["-y", "@inkrelay/mcp"]
env = { INKRELAY_API_KEY = "ir_test_your_key" }

Docs search is a separate hosted server at https://docs.inkrelay.app/mcp (streamable HTTP), for example:

claude mcp add-json inkrelay-docs '{"type":"http","url":"https://docs.inkrelay.app/mcp"}'

Tools

| Tool | What it does | |---|---| | whoami | Organization, plan, mode (test or live) and usage of the key | | list_computers | Computers running the agent and their state | | list_printers | Printers with id, computer, online state, live switch and defaults | | get_printer | Capabilities: papers, trays, dpis, duplex, color, n-up | | update_printer | Display name, live switch, default options, custom paper sizes (admin scope) | | print_pdf | Print a PDF from a URL, base64 or a local file; waits for the final state by default | | print_raw | Print ZPL, ESC/POS or other printer language bytes from text, base64, a URL or a local file | | get_print_job | A job with its state, message and full event history | | wait_for_print_job | Wait until a job is done, error, cancelled or expired | | list_print_jobs | Recent jobs, filtered by printer, computer or state | | cancel_print_job | Cancel a job that is still queued or sent | | reprint_print_job | Print an earlier job's stored file again | | get_usage | Live prints used and included this billing period | | list_events | The event feed (the same events webhooks deliver) | | list_webhooks, create_webhook, ping_webhook | Manage signed webhook endpoints (admin scope) |

Things to try: "Which printers do I have?", "Print this invoice PDF on the A4 laser, two copies, duplex", "Print a 4x6 ZPL test label that says Order 1042", "Why did my last job fail?".

Configuration

| Variable | Default | Meaning | |---|---|---| | INKRELAY_API_KEY | none | Your ir_test_ or ir_live_ key. The server starts without it and tells the model how to get one | | INKRELAY_BASE_URL | https://api.inkrelay.app | Override for a proxy | | INKRELAY_FILE_ROOT | the working directory | Folder that filePath arguments must stay inside. File reads are off when this resolves to /, a drive root or the home folder (common for desktop clients), so set it there. Hidden files and folders are never read, and print_raw reads only printer files (.zpl, .epl, .prn, .pcl, .ps, .escpos, .raw, .bin, .txt) |

print_pdf, print_raw and reprint_print_job send an Idempotency-Key on every job (pass your own with idempotencyKey), so a retried call never prints twice. Jobs carry source: "inkrelay-mcp". With a live key, jobs print on paper and count toward your plan, so keep tool approval on in your client.

Building printing into your own code

The MCP server is for operating printers from an assistant. To add printing to an application, use the SDKs, @inkrelay/sdk and inkrelay, and give your coding agent the inkrelay-printing skill.

Docs: https://docs.inkrelay.app/ai

Development

pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build

License

MIT