Enables an AI client to discover scanners, manage scan jobs, and perform batch document capture using SANE backends.
Also known as jacksenechal/scan-mcp
- Stars
- 6
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Oct 27, 2026
- License
- MIT
What is scan MCP?
scan enables an AI client to discover scanners, manage scan jobs, and perform batch document capture using SANE backends. It exposes 8 tools, such as list_devices, get_device_options, start_scan_job.
Summary generated from the project's README
About scan MCP server
Automating document capture and scanner management from an AI client is what scan-mcp enables for developers working on Linux systems. This server connects to SANE backends to discover hardware, manage scan jobs, and handle batch document processing. It is designed for local-first privacy using stdio transport, but it also supports a streamable HTTP transport via server-sent events for network-based deployments.
Users can interact with the server through specific tools like list_devices to find hardware, start_scan_job to initiate captures with settings for resolution, color mode, and duplexing, or get_job_status to monitor progress. The system handles complex tasks such as multipage assembly using tiffcp and carrier-sheet detection via ImageMagick. It organizes all output, including TIFF files and manifest.json files, into a designated inbox directory defined by the INBOX_DIR environment variable.
What you can do with it
- 1Batch document scanningInstruct the AI to scan a stack of papers using the automatic document feeder and duplex mode.
- 2Carrier sheet removalPerform a scan where the AI identifies and crops out carrier sheets from the resulting images.
Written from the project's README. Every use case is checked against a quote from it.
How to install scan MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall scan MCP in Claude Code
$ claude mcp add scan-mcp -- npx -y scan-mcpInstall scan MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"scan-mcp": {
"command": "npx",
"args": [
"-y",
"scan-mcp"
]
}
}
}Install scan MCP in VS Code
.vscode/mcp.json
{
"servers": {
"scan-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"scan-mcp"
]
}
}
}Install scan MCP in VS Code CLI
$ code --add-mcp '{"name":"scan-mcp","type":"stdio","command":"npx","args":["-y","scan-mcp"]}'Install scan MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"scan-mcp": {
"command": "npx",
"args": [
"-y",
"scan-mcp"
]
}
}
}Install scan MCP in Codex
$ codex mcp add scan-mcp -- npx -y scan-mcpInstall scan MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.scan-mcp] command = "npx" args = ["-y", "scan-mcp"]
Install scan MCP in Gemini CLI
$ gemini mcp add -s user scan-mcp npx -- -y scan-mcpInstall scan MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"scan-mcp": {
"command": "npx",
"args": [
"-y",
"scan-mcp"
]
}
}
}scan MCP tools 8
Detected from the READMElist_devicesget_device_optionsstart_scan_jobget_job_statuscancel_joblist_jobsget_manifestget_events
Configuration
INBOX_DIR
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubMinimal 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
- zod-validated inputs; the JSON Schemas in
schemas/document the contract and are contract-tested - 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_jobwithout adevice_idto auto-select a scanner and begin scanning. - Artifacts are written under
INBOX_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.
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
- Default port is
3001; setMCP_HTTP_PORTto override (for exampleMCP_HTTP_PORT=3333 scan-mcp --http). - Binds
127.0.0.1by default. SetMCP_HTTP_HOSTto expose it on other interfaces (for exampleMCP_HTTP_HOST=::for all, or a LAN address); the server has no authentication, so only do that on a trusted network. - 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; widen the bind address only on a trusted internal network.
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 --httpto launch the streamable HTTP transport when running on another machine. - CLI help:
scan-mcp --help - From source (for development):
npm installnpm run build
- For Cline setup, and other automated agentic installation, see llms-install.md
System Requirements
- Linux with SANE utilities:
scanimage - TIFF tools:
tiffcp(multipage assembly) and ImageMagickconvert(carrier-sheet detection and cropping); preflight requires both
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(default:scanimage): override the binary path.TIFFCP_BIN/IM_CONVERT_BIN(defaults:tiffcp/convert): multipage assembly and image analysis 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.LOG_LEVEL(default:info): pino log level.MCP_HTTP_PORT(default:3001): TCP port for the HTTP transport.MCP_HTTP_HOST(default:127.0.0.1): bind address 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_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(page_count|none),page_count}: split the batch into documents ofpage_countpagesoutput_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
- Begin a scanning job; omitting
-
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)
- Fetch a job's
-
get_events
- Retrieve a job's
events.jsonllog. - Inputs:
job_id(string)
- Retrieve a job's
See JSON Schemas in schemas/ for input shapes. Runtime validation is zod (src/server/register.ts); the schemas document the contract and tests assert against them.
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 registrationsrc/services/*— hardware interface and job orchestrationschemas/— JSON Schemas documenting the tool contracts (used by tests)docs/— architecture, conventions, and deep dives
Development
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
Roadmap
Tracking ideas and future improvements are documented in docs/ROADMAP.md.
scan MCP questions
How do I add scan MCP to Claude Code?
Run claude mcp add scan-mcp -- npx -y scan-mcp in your terminal. Add --scope user to make it available in every project.
How do I add scan MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does scan MCP provide?
It exposes 8 tools, including list_devices, get_device_options, start_scan_job, get_job_status, cancel_job.
Can I use this server over a network?
Yes, you can use the streamable HTTP transport by running scan-mcp --http, which uses server-sent events (SSE) for tool output.
Is there any authentication for the HTTP transport?
No, there is currently no authentication for the HTTP transport, so it should only be used on a trusted network.
How can I test the server without a physical scanner?
You can use the SCAN_MOCK environment variable to mock SANE calls and generate fake TIFF files for testing.