scanner-mcp is an MCP server that lets Claude (or any MCP client) discover and control physical document scanners to digitize and read paper documents.
Discover scanners (list_scanners): Find all reachable scanners, including network (eSCL/AirScan/mDNS) and USB devices (WIA on Windows, SANE on Linux/macOS, optional TWAIN). Returns scanner IDs, names, backends, connection types, and supported sources.
Scan documents (scan_document): Trigger a scan with fine-grained control:
Source: flatbed glass (platen), document feeder (adf), or duplex feeder (adf-duplex)
Resolution: 150 DPI (fast), 300 DPI (documents), or 600 DPI (fine detail)
Color mode: full color, grayscale, or 1-bit black & white (lineart)
Output format: PNG, JPEG, or PDF (ideal for multi-page archives)
Save scans: Output files saved to a configurable directory (default ~/Scans).
Return inline images: Scanned pages returned directly so Claude can view and analyze them immediately.
OCR text extraction: Extract text from scanned pages using Tesseract (requires Tesseract + pytesseract).
Cross-platform: Works on Windows (WIA/TWAIN), Linux (SANE), and macOS (SANE/eSCL), with backends auto-detected.
Local-only processing: All scanning is performed locally — no data is sent to the cloud.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@scanner-mcp List my scanners"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Tool | Purpose |
| Discover every scanner reachable from this machine (network + USB). |
| 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.
Related MCP server: @parserelay/mcp
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]"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 OCRPlatform 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.
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.
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 mcp add scanner -- scanner-mcpRestart the client, then ask Claude: "List my scanners" or "Scan the document on the glass and read 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 pdfVariable | Default | Meaning |
|
| Where scans are written. |
|
| Log level. |
scan_document optionsscanner_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).
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.
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.
MIT
List all scanners reachable from this machine.
Discovers network scanners over mDNS (eSCL/AirScan) and local USB scanners via the
platform driver stack (WIA on Windows, SANE on Linux/macOS). Returns a JSON array of
scanners with their id (pass this to scan_document), name, backend,
connection type and supported sources.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral details: discovery methods, platform-specific drivers, and return fields. No destructive behavior is indicated, and there is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs, front-loaded with the main purpose. It could be slightly more concise, but it is well-structured and provides necessary technical details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (indicated present), the description covers the tool's purpose, discovery methods, and return format. It references the sibling tool 'scan_document', making the context complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline 4 applies. Schema coverage is 100%, and the description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all reachable scanners, specifies discovery methods (mDNS, USB), and describes the return format. It distinguishes from sibling 'scan_document' by mentioning the returned 'id' field for use with that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use: before scanning with 'scan_document'. It does not explicitly state when not to use, but the context is sufficient given the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a document and return it so Claude can read it.
Args:
scanner_id: Which scanner to use (from list_scanners). If omitted and exactly
one scanner is found, that one is used; if several are found, an error lists them.
source: auto | platen (flatbed glass) | adf (document feeder) |
adf-duplex (feeder, both sides).
resolution: DPI (150 fast, 300 documents, 600 fine). Default 300.
color_mode: color | gray | lineart (1-bit black & white).
output_format: png | jpeg | pdf. PDF is best for multi-page archives;
images let Claude view the page inline.
save_dir: Folder to save the scan in. Defaults to ~/Scans (or $SCANNER_MCP_SAVE_DIR).
return_image: If true and the output is an image, the page images are returned
inline so Claude can read the document directly. Ignored for PDF.
ocr: If true, also OCR each page to text (requires Tesseract + pytesseract).
Returns a summary plus, when applicable, inline page images and/or OCR text.
| Name | Required | Description | Default |
|---|---|---|---|
| ocr | No | ||
| source | No | auto | |
| save_dir | No | ||
| color_mode | No | color | |
| resolution | No | ||
| scanner_id | No | ||
| return_image | No | ||
| output_format | No | png |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with scanning. The description adds behavioral details such as creating files, returning inline images, and OCR, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear intro followed by bullet-pointed parameter details. It is somewhat lengthy (8 parameters) but front-loaded with the main purpose. Every sentence adds value, though could be slightly more concise if parameter details were in schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (none required), no output schema, the description covers all parameter details, default behaviors, return values (summary, inline images, OCR text), and error conditions (missing scanner). This is sufficient for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains all 8 parameters including defaults, options, and effects (e.g., source options, resolution values, color modes, output formats). This fully compensates for the lack of schema parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Scan a document and return it so Claude can read it,' clearly specifying the action (scan), resource (document), and purpose. It distinguishes from the sibling tool 'list_scanners' by focusing on scanning rather than listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (scanning documents) and provides guidance on the scanner_id parameter, referencing list_scanners for obtaining scanner IDs, and describing default behavior and error handling for missing scanner IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_scannersscan_documentScored across 2 tools
The two tools have completely distinct purposes: one discovers available scanners, the other performs a scan. No overlap or ambiguity exists.
Both tool names follow a consistent verb_noun pattern with underscores (list_scanners, scan_document), making them predictable and clear.
With only 2 tools, the set is minimal but adequate for the focused domain of document scanning. Slightly under the typical 3-15 range, but still reasonable.
The tools cover the core workflow of discovering and scanning documents with many configuration options. Minor gaps like canceling a scan or checking scanner status are present but not critical.
PDF tools for Claude: merge, split, compress, convert, OCR & more. Requires a PDFHaul API key.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Agent-native document parsing: PDF, scans and FR/EU invoices to structured JSON or Markdown.
