Scan MCP server

scan-mcp

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

Features

• 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).

Quick Start (local stdio, default)

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.
• Call startscanjob without a device_id to auto-select a scanner and begin scanning.
• Artifacts are written under INBOXDIR per job: job-/page.tiff, doc.tiff, manifest.json, events.jsonl. When cropcarriersheets is set and a carrier sheet is detected, a page_*.cropped.tiff derivative is also written per affected page.

Streamable HTTP transport

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

scan-mcp --http

this transport.

• Default port is 3001; set MCPHTTPPORT to override (for example MCPHTTPPORT=3333 scan-mcp --http).
• Binds all interfaces (::) by default; set MCPHTTPHOST to restrict (for example MCPHTTPHOST=127.0.0.1 when 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

• There is currently no authentication; this is intended for internal LAN networking

Install

• 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
• Use npx scan-mcp --http to launch the streamable HTTP transport when running on another machine.
• CLI help: scan-mcp --help
• From source (for development):
• npm install
• npm run build
• For Cline setup, and other automated agentic installation, see llms-install.md

System Requirements

• Linux with SANE utilities: scanimage (and optionally scanadf)
• TIFF tools: tiffcp (preferred) or ImageMagick convert

Environment Variables

• SCAN_MOCK (default: false): mock SANE calls and generate fake TIFFs for testing.
• INBOXDIR (default: scanneddocuments/inbox): base directory for job runs and artifacts.
• SCANIMAGEBIN / SCANADFBIN (defaults: scanimage / scanadf): override binary paths.
• TIFFCPBIN / IMCONVERT_BIN (defaults: tiffcp / convert): multipage assembly tools.
• SCANEXCLUDEBACKENDS (CSV): backends to exclude (e.g., v4l).
• SCANPREFERBACKENDS (CSV): preferred backends (e.g., epjitsu,epson2).
• PERSISTLASTUSED_DEVICE (default: true): persist and lightly prefer last used device.
• MCPHTTPPORT (default: 3001): TCP port for the HTTP transport.

API

Tools

• listdevices**
• Discover connected scanners with backend details.
• Inputs: none.

Shortened. The full README is on GitHub.