# Epson ET-1810 MCP server

Connects Claude to an Epson ET-1810 EcoTank printer on Windows.

Read-only facts (status, ink, usage, firmware) come from the printer's own web
panel over the network. Printing and queue control go through the Windows
spooler, with pages rendered locally and painted onto a driver device context so
print options are genuinely applied rather than ignored.

## Tools

| Tool | What it does |
| --- | --- |
| `get_printer_status` | Device state from the printer plus spooler queue state. Each half reports its own reachability. |
| `get_ink_levels` | Per-tank readings. See the note on ink levels below. |
| `get_usage_stats` | Lifetime page counters: totals, mono/colour, by paper size, by function, by print language. |
| `get_device_info` | Model, firmware, MAC addresses, Epson Connect registration. |
| `list_printers` | Every Windows printer with driver, port, default flag and status flags. |
| `get_print_capabilities` | What the driver supports: colour, duplex, max copies, paper sizes, resolutions. |
| `print_file` | Print a PDF, image or text file with copies, colour, orientation, paper, quality, duplex and page range. |
| `list_print_jobs` | Jobs in the queue with status and page progress. |
| `control_print_job` | Cancel, pause, resume or restart a job. |

Supported files: `.pdf`; images `.png .jpg .jpeg .bmp .gif .tif .tiff .webp`;
text `.txt .log .md .csv`.

## Two honest limitations of this printer

**Ink levels cannot be read.** The ET-1810 is an EcoTank with no electronic ink
level sensor. Epson's own web panel draws each tank as a solid grey box rather
than a fill level, and this server reports the same thing: `level_known: false`
with `level_percent: null`. Any tool that gives you a percentage for this model
is inventing it. Check the tanks on the front of the printer.

**There is no automatic two-sided printing.** The driver reports
`supports_duplex: false`, so `duplex` values other than `simplex` are rejected
with an explanation instead of being silently ignored.

## Setup

The printer is reached two ways, and both must work.

1. **Network panel** — set `EPSON_PRINTER_HOST` to the printer's IP address or
   hostname (its address is on the printer's network status sheet, or in your
   router's client list). Without it, the panel-backed tools say so instead of
   guessing.
2. **Windows printer** — the printer installed on a **WSD port**. Set
   `EPSON_PRINTER_NAME` to its name in Windows, or a unique part of it; if the
   variable is unset the Windows default printer is used. Installed names
   usually look like `EPSONXXXXXX (ET-1810 Series)`, where the digits differ per
   device — check **Settings > Bluetooth & devices > Printers & scanners**.

The Windows Print Spooler service must be running:

```powershell
sc.exe config Spooler start= auto
sc.exe start Spooler
```

If the printer is not installed in Windows, add it through **Settings >
Bluetooth & devices > Printers & scanners > Add device**, which discovers it on
the network and creates a WSD connection.

Do not add it as a Standard TCP/IP (RAW, port 9100) printer. The printer
accepts only these document formats, which it reports over IPP:

```
application/octet-stream
image/pwg-raster
application/vnd.epson.escpr
```

There is no PDF or PostScript in that list. Over a RAW port nothing negotiates
a format, so the Microsoft IPP Class Driver sends PDF and the printer prints
the PDF source as literal text (pages of `/BitsPerComponent` and friends). A
WSD or genuine IPP connection negotiates PWG Raster, which works. Epson's own
ESC/P-R driver also works if you prefer to install it.

## Client configuration

`.mcp.json` in this repo carries placeholder values. Fill in your own printer
address and Windows printer name there, or in
`%APPDATA%\Claude\claude_desktop_config.json` for Claude Desktop:

```json
{
  "mcpServers": {
    "epson-et1810": {
      "command": "C:\\path\\to\\epson-et1810-mcp\\.venv\\Scripts\\epson-mcp.exe",
      "args": [],
      "env": {
        "EPSON_PRINTER_HOST": "printer.local",
        "EPSON_PRINTER_NAME": "EPSON ET-1810 Series"
      }
    }
  }
}
```

Claude Desktop needs the absolute path to the executable. The executable is
self-contained in the project's virtual environment, so the client does not
need `uv` or Python on its PATH.

## Development

```powershell
uv sync
.venv\Scripts\python.exe -m epson_mcp   # run the server on stdio
```

`winprint.print_file` accepts an `output_file` argument, which renders to a file
instead of paper for drivers that support it (such as Microsoft Print to PDF).
This is how the print pipeline is tested without wasting paper.