TimeVerse Printer MCP Server

English | 中文

A comprehensive Model Context Protocol (MCP) server for printer control, supporting multiple communication protocols and page description languages. Lets AI agents discover printers, print documents, query status, and manage print queues.

Features

7 Transport Methods

6 Page Description Languages

PDF, PCL 5/6, ESC/POS (receipts), ZPL (labels), Plain Text, Images (PNG/JPEG/BMP)

18 MCP Tools

• Discovery (3): list_printers, discover_printers, get_printer_info
• Printing (6): print_file, print_text, print_image, print_raw, print_escpos, print_zpl
• Status (2): get_printer_status, get_printer_capabilities
• Queue (5): get_print_jobs, cancel_print_job, cancel_all_jobs, pause_printer, resume_printer
• Management (2): get_default_printer, set_default_printer

Installation

Prerequisites

• Python 3.12+
• Windows (recommended for full Win32 Spooler support) or Linux/macOS (CUPS)

Install

# Clone or copy the project
cd timeverse-printer-mcp

# Create a virtual environment
python -m venv .venv

# Activate it
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Install the package
pip install -e .

Optional: USB Driver (Windows)

For USB printer support on Windows, install Zadig and replace the printer's driver with libusbK or WinUSB.

MCP Client Configuration

Add this to your MCP client config (e.g. Claude Desktop, WorkBuddy):

{
  "mcpServers": {
    "timeverse-printer": {
      "command": "python",
      "args": ["-m", "timeverse_printer_mcp.server"],
      "env": {
        "TIMEVERSE_PRINTER_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Environment Variables

Usage Examples

List Installed Printers

Tool: list_printers(include_network=true)

Discover Network Printers

Tool: discover_printers(method="all", subnet="192.168.1.0/24", timeout=5000)

Print a PDF File

Tool: print_file(
  file_path="C:/Documents/report.pdf",
  printer="HP LaserJet Pro M404",
  copies=2,
  duplex="long-edge",
  color="monochrome"
)

Print a Receipt (ESC/POS)

Tool: print_escpos(
  printer="192.168.1.100:9100",
  commands=[
    {"type": "init"},
    {"type": "align", "params": {"alignment": "center"}},
    {"type": "bold", "params": {"enable": true}},
    {"type": "font_size", "params": {"width": 2, "height": 2}},
    {"type": "text", "value": "My Store"},
    {"type": "feed", "params": {"lines": 1}},
    {"type": "align", "params": {"alignment": "left"}},
    {"type": "text", "value": "Item 1 ......... $10.00"},
    {"type": "text", "value": "Item 2 ......... $5.50"},
    {"type": "feed", "params": {"lines": 1}},
    {"type": "align", "params": {"alignment": "center"}},
    {"type": "qrcode", "value": "https://example.com", "params": {"size": 6}},
    {"type": "cut", "params": {"mode": "full"}}
  ]
)

Print a Label (ZPL)

Tool: print_zpl(
  printer="192.168.1.200:9100",
  zpl="^XA^FO20,20^A0N,50,50^FDHello World^FS^FO20,80^BCN,100,Y,N,N^FD12345678^FS^XZ",
  labels=3
)

Query Printer Status

Tool: get_printer_status(printer="HP LaserJet Pro M404", method="auto")

Manage Print Queue

Tool: get_print_jobs(printer="HP LaserJet Pro M404")
Tool: cancel_print_job(printer="HP LaserJet Pro M404", job_id=42)
Tool: cancel_all_jobs(printer="HP LaserJet Pro M404")
Tool: pause_printer(printer="HP LaserJet Pro M404")
Tool: resume_printer(printer="HP LaserJet Pro M404")

Printer Identifier Formats

The printer parameter accepts multiple formats:

Architecture

MCP Tool Layer (18 tools)
    |
Transport Router (auto-selects best transport)
    |
Transport Layer (Win32 Spooler / IPP / Raw / LPD / USB / Serial / CUPS)
    |
Document Layer (PDF / Image / Text / ESC/POS / ZPL / PCL)
    |
Discovery Layer (mDNS / SNMP / Win32 Enum / USB Scan)

Dependencies

Core

• mcp — Official MCP Python SDK (FastMCP)
• pywin32 — Win32 Print Spooler API (Windows only)
• pyipp — IPP client
• pyusb — USB communication
• pyserial — Serial port communication
• pysnmp — SNMP status queries
• zeroconf — mDNS/Bonjour discovery
• pycups — CUPS API (Linux/macOS only)

Document Processing

• pypdf — PDF reading
• reportlab — PDF generation
• Pillow — Image processing
• python-escpos — ESC/POS command library

Project Structure

timeverse-printer-mcp/
├── src/timeverse_printer_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/                 # 18 MCP tools
│   │   ├── discovery.py       # list_printers, discover_printers, get_printer_info
│   │   ├── printing.py        # print_file, print_text, print_image, print_raw, print_escpos, print_zpl
│   │   ├── status.py          # get_printer_status, get_printer_capabilities
│   │   ├── queue.py           # get_print_jobs, cancel_print_job, cancel_all_jobs, pause_printer, resume_printer
│   │   └── management.py      # get_default_printer, set_default_printer
│   ├── transports/            # 7 transport implementations + router
│   │   ├── base.py            # Abstract transport base class
│   │   ├── router.py          # Transport auto-router
│   │   ├── win32_spooler.py   # Windows Print Spooler (pywin32)
│   │   ├── ipp_transport.py   # IPP (pyipp)
│   │   ├── raw_socket.py      # Raw Socket (port 9100)
│   │   ├── lpd.py             # LPD/LPR (port 515)
│   │   ├── usb_transport.py   # USB (pyusb)
│   │   ├── serial_transport.py# Serial (pyserial)
│   │   ├── cups_transport.py  # CUPS (pycups, Linux/macOS)
│   │   └── snmp_status.py     # SNMP status query (pysnmp)
│   ├── documents/             # Document handlers
│   │   ├── pdf_handler.py     # PDF processing
│   │   ├── image_handler.py   # Image processing
│   │   ├── text_handler.py    # Text formatting
│   │   ├── escpos_builder.py  # ESC/POS command builder
│   │   ├── zpl_builder.py     # ZPL command builder
│   │   └── pcl_builder.py     # PCL command builder
│   ├── discovery/             # Printer discovery
│   │   ├── mdns_discovery.py  # mDNS/Bonjour discovery
│   │   ├── snmp_scan.py       # SNMP subnet scanner
│   │   ├── win32_enum.py      # Windows printer enumeration
│   │   └── usb_scan.py        # USB device scanner
│   └── utils/                 # Shared utilities
│       ├── types.py           # Data models (PrinterTarget, PrintResult, etc.)
│       ├── errors.py          # Error handling
│       ├── logger.py          # Logging
│       └── platform.py        # Platform detection
├── tests/
├── pyproject.toml
└── README.md

License

MIT