Scan MCP

🚀 scan-mcp

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

✨ Features

• A small, typed MCP server that provides tools for device discovery and scan jobs.
• Inputs are validated by JSON Schema, with deterministic and typed outputs.
• Smart device selection (prefers ADF/duplex and avoids camera backends), along with robust defaults.
• Local-first transports: stdio by default to keep everything on the device, and 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 start_scan_job without a device_id to auto - select a scanner and start scanning.
• Artifacts are written under INBOX_DIR per job: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl.

Streamable HTTP Transport

If you prefer to attach the scanner to another machine on your network, scan-mcp also supports the streamable HTTP transport:

scan-mcp --http

• The default port is 3001; set MCP_HTTP_PORT to override (e.g., MCP_HTTP_PORT=3333 scan-mcp --http).
• HTTP responses use server - sent events (SSE) for streaming tool output; clients such as Claude Desktop and Windsurf support this transport.
• Currently, there is no authentication; this is intended for internal LAN networking.

📦 Installation

• Run with npx: npx scan-mcp (recommended)
  • The CLI runs a quick pre - flight check for Node 22+ and required scanner/image tools and provides installation hints if anything is missing.
  • See the 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.

🔧 Technical Details

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.
• 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 the last used device.
• MCP_HTTP_PORT (default: 3001): TCP port for the HTTP transport.

📚 Documentation

API - Tools

• list_devices

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

• get_device_options

  • Get SANE options for a specific device.
  • Inputs:
    • device_id (string): Target device identifier.

• start_scan_job

  • Begin a scanning job; omitting device_id triggers auto - selection and default options.
  • Inputs (all optional unless noted):
    • device_id (string)
    • resolution_dpi (integer, 50–1200)
    • color_mode (Color | Gray | Lineart)
    • 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, default tiff)
    • tmp_dir (string)

• get_job_status

  • Inspect job state and artifact counts.
  • Inputs:
    • job_id (string)

• cancel_job

  • Request job cancellation; best effort during scan loops.
  • Inputs:
    • job_id (string)

• list_jobs

  • List recent jobs from the inbox directory.
  • Inputs (optional):
    • limit (integer, max 100)
    • state (running | completed | cancelled | error | unknown)

• get_manifest

  • Fetch a job's manifest.json.
  • Inputs:
    • job_id (string)

• get_events

  • Retrieve a job's events.jsonl log.
  • Inputs:
    • job_id (string)

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

How Selection and Defaults Work

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

• Selection and defaults: docs/SELECTION.md

Project Layout

• 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 in - depth guides

💻 Usage Examples

Development

• npm run dev (stdio MCP server), npm run dev:http (HTTP transport)
• make verify runs lint, typecheck, and tests
• Conventions: docs/CONVENTIONS.md and architecture in docs/BLUEPRINT.md

Roadmap

Tracking ideas and future improvements are documented in docs/ROADMAP.md.