Scan

You can run a minimal MCP server locally to capture scans from SANE backends, batch pages, and assemble multi-page documents. It runs on your machine by default and can also stream over HTTP to other machines on your network if you enable the transport. This guide shows practical steps to install, configure, and use the scanner MCP server with a client.

How to use

Configure your MCP client to connect to the stdio MCP server provided by the scanner tool. The server runs via a simple command that starts the MCP process on your machine and communicates over standard input/output for privacy-first operation.

How to install

Prerequisites you need before starting:

• Node.js 22 or later is required.
• Linux with SANE backends like scanimage (and optionally scanadf).
• TIFF tools such as tiffcp (preferred) or ImageMagick convert.

Install and run the scanner MCP server using the recommended approach:

# Quick start: run the MCP server locally via stdio
npx scan-mcp

Additional notes and configuration

The server is configured to write artifacts for each job under a base inbox directory you specify when launching the process. A typical setup points to a local inbox like the following.

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

Configuration and defaults

Defaults aim for a sensible balance: common scanning resolution, color/gray options, and automatic selection of a suitable device when available. You can customize options through the API to specify device, DPI, color mode, source, page size, and output format. The server stores per-job artifacts such as TIFF pages and a manifest for downstream processing.

Environment variables you may use

The server supports several environment variables to tailor its behavior. Use them when launching the MCP server to control mock behavior, device selection, and transport defaults.

# Example environment variables
INBOX_DIR=~/Documents/scanned_documents/inbox
SCAN_MOCK=false
SCANIMAGE_BIN=scanimage
SCANADF_BIN=scanadf
TIFFCP_BIN=tiffcp
IM_CONVERT_BIN=convert
PERSIST_LAST_USED_DEVICE=true
MCP_HTTP_PORT=3001

Troubleshooting tips

If you encounter device discovery or scan errors, verify that the SANE backends are installed and accessible, confirm the inbox directory exists and is writable, and check that required tooling (scanimage, tiffcp or convert) is in your PATH.

Available tools

list_devices

Discover connected scanners with backend details.

get_device_options

Get SANE options for a specific device.

start_scan_job

Begin a scanning job; omit device_id to auto-select and use defaults.

get_job_status

Inspect a job's state and artifact counts.

cancel_job

Request cancellation of an active scan job.

list_jobs

List recent jobs from the inbox directory.

get_manifest

Fetch a job's manifest.json.

get_events

Retrieve a job's events.jsonl log.