# mcp-printer

![License: MIT](https://img.shields.io/github/license/AminHA1248/mcp-printer?color=blue)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)

> **Let Claude print documents** on any USB or network printer.

A **generic MCP server** that exposes a printing tool to Claude (and any other MCP
client). It works with **network printers** through the standard **IPP / AirPrint /
Mopria** protocol and with **locally installed printers** through the platform print
stack — the **Windows spooler** on Windows and **CUPS** (`lp`) on Linux/macOS. No
vendor-specific driver code.

When Claude needs to put something on paper — a PDF you point it at, a note it just
wrote, a shopping list — it can call `print_document` and the job goes straight to
your printer.

## What it exposes

| Tool | Purpose |
|------|---------|
| `list_printers` | Discover every printer reachable from this machine (network + installed). |
| `print_document` | Print a file from disk, or a piece of text, with copies/duplex/color/paper options. |

Backends are auto-detected and degrade gracefully — the same server runs on any OS and
lights up whatever printers it can reach:

- **IPP** (`_ipp._tcp` mDNS) — driverless network printers (anything AirPrint/Mopria
  capable). *Cross-platform*; the tiny IPP wire protocol is implemented in-package, no
  extra tooling needed.
- **Windows** — printers installed in Windows (USB and network), driven via PowerShell.
  Text prints natively; other file types are handed to the app registered to print them.
- **CUPS** (`lp`) — printers configured in CUPS on **Linux** and **macOS** (USB and
  network), with full option support (copies, duplex, color, media).

## Install

```bash
pip install mcp-printer
```

<details>
<summary>Or install from source (for development)</summary>

```bash
git clone https://github.com/AminHA1248/mcp-printer
cd mcp-printer
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -e .
```
</details>

Platform prerequisites:

- **Windows**: nothing extra — the spooler and PowerShell ship with Windows. Install the
  printer's normal Windows driver so it appears in *Printers & scanners*.
- **Linux**: CUPS with the queue configured (`lp`/`lpstat`, usually via the `cups`
  package).
- **macOS**: nothing extra — CUPS is built in; add the printer in System Settings.
- **Network printers**: just be on the same LAN/subnet; mDNS handles discovery.

## Connect it to Claude

### Claude Desktop — one-click extension (easiest)
Download `mcp-printer-<version>.mcpb` from the
[latest release](https://github.com/AminHA1248/mcp-printer/releases/latest) and open it
via **Settings → Extensions → Install extension…**. Requires Python 3.10+ with
`pip install mcp-printer` (the extension tells you if it's missing). Details:
[docs/EXTENSION.md](docs/EXTENSION.md).

### Claude Desktop — manual config
Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "printer": {
      "command": "mcp-printer"
    }
  }
}
```

If `mcp-printer` isn't found (its Scripts/bin dir isn't on Claude's PATH), use the full
path to the launcher — e.g. `C:\Users\you\...\Scripts\mcp-printer.exe` on Windows or
`/path/to/venv/bin/mcp-printer` on macOS/Linux — or `python -m mcp_printer.server`.

### Claude Code (CLI)
```bash
claude mcp add printer -- mcp-printer
```

Restart the client, then ask Claude: *"List my printers"* or *"Print this report
double-sided."*

## How you actually run it

You normally **don't launch anything yourself** — Claude Desktop/Code starts the
`mcp-printer` server in the background (per the config above) and calls its tools when
you ask. Running `mcp-printer` by hand just starts the MCP server, which waits silently
for JSON-RPC on stdin; it is not an interactive shell.

To test the hardware **without Claude**, use the bundled CLI, [`test_print.py`](test_print.py):

```bash
# from the project folder, using the venv's Python
python test_print.py --list                # discover printers
python test_print.py                       # print a small text test page
python test_print.py --printer "<id>" --file report.pdf --duplex long-edge --copies 2
```

## Configuration (env vars)

| Variable | Default | Meaning |
|----------|---------|---------|
| `MCP_PRINTER_LOG` | `INFO` | Log level. |

## `print_document` options

`printer_id` (from `list_printers`; auto-selects the system default or only printer),
`file_path` **or** `text` (one of the two), `copies` (1–99), `duplex`
(`auto`/`off`/`long-edge`/`short-edge`), `color_mode` (`auto`/`color`/`monochrome`),
`media` (paper size keyword, e.g. `iso_a4_210x297mm`, `na_letter_8.5x11in`).

## Notes & limitations

- **IPP** covers most printers sold in the last ~decade. The document is sent as-is
  (with a MIME hint from the file extension), so stick to formats printers understand
  natively: **PDF, JPEG, plain text**. PNG and others depend on the model.
- The **Windows backend** prints text reliably; for other file types it uses the shell
  *PrintTo* verb, which needs an installed app that registers a print handler for that
  extension. For PDFs on a bare Windows install, prefer the IPP backend (network
  printers) instead. Duplex/color/media are driver preferences on Windows and are not
  overridden per-job.
- HTTPS IPP devices use self-signed certs, so TLS verification is disabled for them
  (typical for LAN printers); prefer a trusted network.
- This server performs local hardware I/O only — it does not send anything to the cloud.

## Privacy Policy

mcp-printer runs entirely on your machine and **collects no data** — no telemetry, no
analytics, no network transmission of your documents beyond the printer you select.
Full policy: **[PRIVACY.md](https://github.com/AminHA1248/mcp-printer/blob/main/PRIVACY.md)**.

## License

MIT