Content
# mcp-printer
> **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
