io.github.jacksenechal/scan-mcp
MCP server for scanner discovery and batch capture via SANE
Open source Open in the app JSON README (API)
About
MCP server for scanner discovery and batch capture via SANE
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- jacksenechal
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Stars
- 6
- Forks
- 5
- Last push
- 2026-08-03T18:11:24Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:12
- Updated
- 2026-08-29 04:00:12
- Origin id
io.github.jacksenechal/scan-mcp
README
<p align="center">
<img src="docs/assets/icon.png" alt="scan-mcp logo" width="96">
</p>
<h1 align="center">scan-mcp</h1>
[](https://github.com/jacksenechal/scan-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/scan-mcp)
[](https://www.npmjs.com/package/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 `start_scan_job` without a `device_id` to auto-select a scanner and begin scanning.
- Artifacts are written under `INBOX_DIR` per job: `job-*/page_*.tiff`, `doc_*.tiff`, `manifest.json`, `events.jsonl`. When `crop_carrier_sheets` 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:
```bash
scan-mcp --http
```
- Default port is `3001`; set `MCP_HTTP_PORT` to override (for example `MCP_HTTP_PORT=3333 scan-mcp --http`).
- Binds all interfaces (`::`) by default; set `MCP_HTTP_HOST` to restrict (for example `MCP_HTTP_HOST=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
this transport.
- 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](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.
- `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.
## 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`): 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, default `tiff`)
- `tmp_dir` (string)
- `crop_carrier_sheets` (boolean, default `false`): detect carrier-sheet leading-edge band and write cropped page derivatives; raw pages are kept
- **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, reasonable color mode, and ADF/duplex when available. Full details on scoring and fallbacks live in 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 deep dives
## 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`.