scan-mcp

Minimal MCP server for scanner capture (ADF/duplex/page-size), batching, and multipage assembly.

- Small, typed MCP server exposing tools for device discovery and scan jobs
- JSON Schema–validated inputs with deterministic, typed outputs
- Smart device selection (prefers ADF/duplex, avoids camera backends), robust defaults
- Local-first transports: stdio by default to keep everything on-device, optional HTTP for your own network deployments

Note: This package targets Node 22 and Linux SANE backends (scanimage).

Add a server entry to your MCP client configuration:

{ "mcpServers": { "scan": { "command": "npx", "args": [ "-y", "scan-mcp" ], "env": { "INBOX_DIR": "~/Documents/scanned_documents/inbox" } } } }

- This invocation runs over stdio for a privacy-first, single-machine setup.
- Callstart_scan_jobwithout adevice_idto auto-select a scanner and begin scanning.
- Artifacts are written underINBOX_DIRper job:job-/page_.tiff,doc_.tiff,manifest.json,events.jsonl. Whencrop_carrier_sheetsis set and a carrier sheet is detected, apage_.cropped.tiffderivative is also written per affected page.

Prefer to attach the scanner to another machine on your network?scan-mcpalso supports the streamable HTTP transport:

- Default port is3001; setMCP_HTTP_PORTto override (for exampleMCP_HTTP_PORT=3333 scan-mcp --http).
- Binds all interfaces (::) by default; setMCP_HTTP_HOSTto restrict (for exampleMCP_HTTP_HOST=127.0.0.1when a reverse proxy fronts the server).
- HTTP responses use server-sent events (SSE) for streaming tool output; clients such as Claude Desktop and Windsurf support this transport.
- There is currently no authentication; this is intended for internal LAN networking

- Run with npx:npx scan-mcp(recommended)

- The CLI runs a quick preflight check for Node 22+ and required scanner/image tools and prints installation hints if anything is missing.
- See recommended server config above

- Linux with SANE utilities:scanimage(and optionallyscanadf)
- TIFF tools:tiffcp(preferred) or ImageMagickconvert

- SCAN_MOCK(default:false): mock SANE calls and generate fake TIFFs for testing.
- INBOX_DIR(default:scanned_documents/inbox): base directory for job runs and artifacts.
- SCANIMAGE_BIN/SCANADF_BIN(defaults:scanimage/scanadf): override binary paths.
- TIFFCP_BIN/IM_CONVERT_BIN(defaults:tiffcp/convert): multipage assembly tools.
- SCAN_EXCLUDE_BACKENDS(CSV): backends to exclude (e.g.,v4l).
- SCAN_PREFER_BACKENDS(CSV): preferred backends (e.g.,epjitsu,epson2).
- PERSIST_LAST_USED_DEVICE(default:true): persist and lightly prefer last used device.
- MCP_HTTP_PORT(default:3001): TCP port for the HTTP transport.

- Discover connected scanners with backend details.
- Inputs: none.

- Get SANE options for a specific device.
- Inputs:

- device_id(string): Target device identifier.

- Begin a scanning job; omittingdevice_idtriggers auto-selection and default options.
- Inputs (all optional unless noted):

- device_id(string)
- resolution_dpi(integer, 50–1200)
- color_mode(Color|Gray|Lineart): color_mode defaults to Lineart (document-first); at >= 600dpi it defaults to Color, since high-dpi capture usually means artwork/photos where 1-bit destroys information. Pass color_mode explicitly to override either default; high dpi is the only signal used.
- source(Flatbed|ADF|ADF Duplex)
- duplex(boolean)
- page_size(Letter|A4|Legal|Custom)
- custom_size_mm{width,height}
- doc_break_policy{type,blank_threshold,page_count,timer_ms,barcode_values}
- output_format(string, defaulttiff)
- tmp_dir(string)
- crop_carrier_sheets(boolean, defaultfalse): detect carrier-sheet leading-edge band and write cropped page derivatives; raw pages are kept

- Inspect job state and artifact counts.
- Inputs:

- job_id(string)

- Request job cancellation; best effort during scan loops.
- Inputs:

- job_id(string)

- List recent jobs from the inbox directory.
- Inputs (optional):

- limit(integer, max 100)
- state(running|completed|cancelled|error|unknown)

- Fetch a job'smanifest.json.
- Inputs:

- job_id(string)

- Retrieve a job'sevents.jsonllog.
- Inputs:

- job_id(string)

See JSON Schemas inschemas/for input shapes. Tests assert against these contracts.

Defaults aim for 300dpi, reasonable color mode, and ADF/duplex when available. Full details on scoring and fallbacks live in docs:

- Selection and defaults:docs/SELECTION.md

- src/mcp.ts— MCP server entry and tool registration
- src/services/*— hardware interface and job orchestration
- schemas/— JSON Schemas used for validation and tests
- docs/— architecture, conventions, and deep dives

- npm run dev(stdio MCP server),npm run dev:http(HTTP transport)
- make verifyruns lint, typecheck, and tests
- Conventions:docs/CONVENTIONS.mdand architecture indocs/BLUEPRINT.md

Tracking ideas and future improvements are documented indocs/ROADMAP.md.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Carryo is a remote MCP server for sharing Claude or ChatGPT-created HTML artifacts as live links.

MCP server that reads and writes the system clipboard — tables, text, code, JSON, URLs, images, and more. Preserves spreadsheet structure (rows/columns) that is lost when pasting into Claude directly. Claude can also write results back to your clipboard.

Read and edit Word (.docx) documents with track changes, comments, footnotes, and structural validation. 18 tools with OOXML-level paraId validation and document auditing.

Read and write data from Microsoft Excel files. Supports text, formulas, sheet creation, and Windows-only live editing.

A simple utility to combine multiple files into a single file.

Interact with Google Docs and Google Drive for document creation, editing, and file management, with support for shared drives.

Create, read, and manipulate Microsoft Word documents.

Manage notes and files in an Obsidian vault. Requires the Obsidian Local REST API plugin.

Provides comprehensive access to an Obsidian vault, allowing AI agents to read, write, search, and manage notes via the Local REST API plugin.

A server for manipulating PDF files, including merging, page extraction, and searching.