Let AI Print: mcp-web-print-pdf Setup Guide

Three hops, all on your own machine, with no cloud relay:

• The AI host (Claude Desktop / Cursor / dsh / Claude Code …) launches the MCP server via npx -y mcp-web-print-pdf over stdio.
• The MCP server translates each tool call into the client WebSocket message it already understands.
• The client renders the PDF locally, submits it to the system print queue, and returns the job result.

AI host (Claude / Cursor / dsh)
   |  stdio: npx -y mcp-web-print-pdf
   v
mcp-web-print-pdf
   |  ws://127.0.0.1:16794/websocket/standard
   v
Web Print Expert client  -->  printer

• The client must be installed and running. MCP is only a bridge; without the client there is no printer channel.
• The response means “submitted”, not “printed”. A job that reaches the system queue counts as success; paused, offline or out-of-paper printers will stall the queue silently.
• Calling a print tool prints. Jobs go straight to the printer by default; pass dry_run: true when you only want to check the layout.
• No cloud path. Only a client running on the same machine works. ChatGPT and claude.ai web only accept remote HTTP MCP, so they cannot reach a local stdio server.

• Web Print Expert client installed and running (default port 16794). Not yet? Download the client.
• Node.js 18+ — hosts pull the server with npx, so no global install is needed; the package is on npm.
• A host that speaks MCP stdio: Claude Desktop, Cursor, dsh, Claude Code, VS Code Copilot, Codex CLI, Cline, Cherry Studio, Trae and similar.

1. Check the client is online

Open the client and confirm it is running and the port is free. Once the host is connected, the first tool to call is getConnectStatus.

2. Register the MCP server in your host

Every host runs the same stdio command; only the config file location and top-level key differ:

{
  "mcpServers": {
    "webprint": {
      "command": "npx",
      "args": ["-y", "mcp-web-print-pdf"],
      "env": { "WEBPRINT_PORT": "16794" }
    }
  }
}

dsh uses a YAML insert instead — different shape, same fields:

- insert:
    - id: mcp-webprint
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: webprint
        transport: stdio
        command: npx
        args:
          - '-y'
          - 'mcp-web-print-pdf'
        toolCallTimeoutMs: 180000

3. Restart the host and confirm it is green

Restart the host and check its MCP panel reports the server as connected. Tool names are namespaced on the model side, e.g. mcp__webprint__printHtml. Call getConnectStatus first, then printHtml with dry_run: true to see whether a preview is generated.

The three option objects map onto the upstream arguments: pdf_options and print_options go through the client whitelist (unknown field names fail loudly), while extra_options accepts any custom keys and echoes them back.

Merge rule: fields you set explicitly win, convenience arguments only fill gaps.

• Using Base64 as a file channel. A stdio message is capped at 10 MB; past that the connection closes before the tool can report an error. For large PDFs or images use printFile or a URL.
• Host timeout beats the job. Most hosts cap a tool call at roughly 60 s, so batches and big files get cut off — split the batch or raise the host timeout (e.g. dsh toolCallTimeoutMs).
• Custom paper names in pdf_options.paperFormat. It only accepts a fixed enum (A0–A6 / Letter / Legal / Tabloid / Ledger); for 80 mm receipts or 100×150 labels use width + height.
• Wrong batchPrint task shape. Each task is { type, data, pdfOptions?, printOptions?, extraOptions? } — content goes in data, not content / url / base64.
• Enabling printFile casually. It reads any local path the model names, so only enable it in trusted environments.
• Copying old tool names. 0.1.0 used snake_case (print_html, list_printers); since 0.2.0 the names match the upstream camelCase methods and the old ones no longer exist.

1. getConnectStatus — continue only when the client is online.
2. getPrinterList — confirm the target printer names the model sees are the ones you expect.
3. printHtml with dry_run: true — a preview or PDF URL in the response means the render path works.
4. Real print — actual output. If nothing comes out, inspect the OS print queue (e.g. Get-PrintJob on Windows) instead of trusting the tool response alone.