scanner-mcp 0.1.1

Generic MCP server exposing a scan tool to network (eSCL/AirScan) and USB (WIA/SANE/TWAIN) scanners.

scanner-mcp

Let Claude scan and read paper documents from any USB or network scanner.

A generic MCP server that exposes a scanning tool to Claude (and any other MCP client). It works with network scanners through the standard eSCL / AirScan / Mopria protocol and with USB scanners through the platform driver stack — WIA on Windows and SANE on Linux/macOS. No vendor-specific driver code.

When Claude needs to read a paper document, it can call scan_document, and the page image is returned inline so Claude can read it directly (optionally OCR'd to text, or saved as PDF).

What it exposes

Tool	Purpose
list_scanners	Discover every scanner reachable from this machine (network + USB).
scan_document	Scan a page/stack and return it as inline images, a saved file, and/or OCR text.

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

• eSCL (_uscan._tcp mDNS) — driverless network MFPs/scanners. Cross-platform.
• WIA — USB (and some network) scanners on Windows, driven via PowerShell COM.
• TWAIN — Windows scanners that expose only a TWAIN data source (older/pro units with no usable WIA driver). Optional; needs pytwain + a TWAIN DSM (see below).
• SANE (scanimage) — USB/network scanners on Linux and macOS.

Install

pip install scanner-mcp
# optional OCR support (also needs the Tesseract binary installed):
pip install "scanner-mcp[ocr]"
# optional TWAIN backend, Windows only (also needs a TWAIN DSM, see below):
pip install "scanner-mcp[twain]"

Or install from source (for development)

git clone https://github.com/AminHA1248/scanner-mcp
cd scanner-mcp
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -e ".[twain]"    # editable install; add [ocr] too if you want OCR

Platform prerequisites:

• Windows: nothing extra for WIA — it and PowerShell ship with Windows. Install the scanner's normal Windows driver so it appears in Devices.
  • TWAIN (optional): install pytwain (pip install -e ".[twain]") and make sure a TWAIN DSM is present. 64-bit Python needs TWAINDSM.dll (shipped by most TWAIN 2.x drivers or the TWAIN DSM redistributable); 32-bit Python can use the classic twain_32.dll. If neither is installed, the TWAIN backend just stays disabled.
• Linux: sudo apt install sane-utils (provides scanimage).
• macOS: brew install sane-backends for USB; network scanners work via eSCL with no extras.
• Network scanners: just be on the same LAN/subnet; mDNS handles discovery.

Connect it to Claude

Claude Desktop — one-click extension (easiest)

Download scanner-mcp-<version>.mcpb from the latest release and open it via Settings → Extensions → Install extension…. Requires Python 3.10+ with pip install scanner-mcp (the extension tells you if it's missing). Details: docs/EXTENSION.md.

Claude Desktop — manual config

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "scanner": {
      "command": "scanner-mcp"
    }
  }
}

If scanner-mcp 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\scanner-mcp.exe on Windows or /path/to/venv/bin/scanner-mcp on macOS/Linux — or python -m scanner_mcp.server.

Claude Code (CLI)

claude mcp add scanner -- scanner-mcp

Restart the client, then ask Claude: "List my scanners" or "Scan the document on the glass and read it."

How you actually run it

You normally don't launch anything yourself — Claude Desktop/Code starts the scanner-mcp server in the background (per the config above) and calls its tools when you ask. Running scanner-mcp 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_scan.py:

# from the project folder, using the venv's Python
python test_scan.py --list                 # discover scanners
python test_scan.py --dpi 300              # scan (auto-selects if only one)
python test_scan.py --scanner "<id>" --source adf --format pdf

Configuration (env vars)

Variable	Default	Meaning
SCANNER_MCP_SAVE_DIR	~/Scans	Where scans are written.
SCANNER_MCP_LOG	INFO	Log level.

scan_document options

scanner_id (from list_scanners; auto if only one), source (auto/platen/adf/adf-duplex), resolution (DPI), color_mode (color/gray/lineart), output_format (png/jpeg/pdf), save_dir, return_image (inline images for Claude to read), ocr (extract text).

Notes & limitations

• eSCL covers most scanners sold in the last ~decade (anything "AirPrint/AirScan" or "Mopria" capable). Older USB-only units go through WIA/SANE instead.
• PDF output for multi-page WIA scans is assembled with Pillow.
• HTTPS eSCL devices use self-signed certs, so TLS verification is disabled for them (typical for LAN scanners); prefer a trusted network.
• This server performs local hardware I/O only — it does not send anything to the cloud.

Privacy Policy

scanner-mcp runs entirely on your machine and collects no data — no telemetry, no analytics, no network transmission of your scans. Scanned files are saved only to your local disk (default ~/Scans) and returned to the MCP client you asked to scan. Full policy: PRIVACY.md.

License

MIT