scan

jacksenechal's avatarfrom jacksenechal

Control scanners via scan-mcp MCP server to capture documents, photos, receipts, and pages. Use when user mentions scanning, scanners, or document types. CRITICAL: call start_scan_job with {} (no params) unless user specifies requirements—server handles intelligent device selection and defaults. Override only for explicit needs like photos (Flatbed+Color+high-res) or duplex stacks (ADF Duplex).

⭐4stars🔀3forks📁View on GitHub🕐Updated Dec 15, 2025
[Document Processing]

When & Why to Use This Skill

The scan-mcp skill enables Claude to directly interface with physical hardware scanners to digitize documents, photos, and receipts. It streamlines the transition from physical to digital by offering intelligent automated device selection and optimized defaults, while allowing for advanced overrides like duplex scanning and high-resolution photo capture to ensure professional-grade results.

Use Cases

  • Business Document Archiving: Efficiently digitize multi-page reports or legal contracts using Auto Document Feeder (ADF) with duplex support for comprehensive record-keeping.
  • Expense and Receipt Management: Capture clear images of physical receipts and invoices, providing a high-quality source for subsequent AI-driven data extraction and financial analysis.
  • High-Fidelity Photo Scanning: Utilize flatbed scanners with specific color mode and high-DPI overrides to preserve physical photographs and delicate media with maximum detail.
  • Automated Office Workflows: Trigger scanning jobs through natural language commands, allowing the MCP server to handle complex hardware configurations and device selection without manual intervention.
namescan
descriptionControl scanners via scan-mcp MCP server to capture documents, photos, receipts, and pages. Use when user mentions scanning, scanners, or document types. CRITICAL: call start_scan_job with {} (no params) unless user specifies requirements—server handles intelligent device selection and defaults. Override only for explicit needs like photos (Flatbed+Color+high-res) or duplex stacks (ADF Duplex).

Scanner Control via scan-mcp

THE GOLDEN RULE

Trust the server defaults. When the user requests a scan without specific requirements:

  • Call start_scan_job({}) with NO parameters
  • Do NOT call list_devices unless the user explicitly asks for a specific scanner
  • Do NOT gather device capabilities "just in case"
  • Server auto-selects device, resolution (300dpi), color mode (Lineart), source (ADF Duplex → ADF → Flatbed)

Only override parameters when the user's intent clearly requires it.

Decision Tree

User request → Analyze intent:

1. Generic scan ("scan this", "scan document")
   → start_scan_job({}) immediately

2. User asks for specific scanner ("use the Epson")
   → list_devices, then start_scan_job({ device_id })

3. Document type needs special handling ("photo", "duplex")
   → Override only specific params needed

Common Overrides

User Intent Parameters
Generic scan {}
Photo scan { source: "Flatbed", color_mode: "Color", resolution_dpi: 600 }
Duplex stack { duplex: true }
OCR-optimized { color_mode: "Gray", resolution_dpi: 300 }

For more mappings, see EXAMPLES.md.

Standard Workflow

  1. Call start_scan_job(params) → receive { job_id, run_dir, state }
  2. Poll get_job_status({ job_id }) until state: "completed"
  3. Results in run_dir:
    • page_*.tiff (captured pages)
    • doc_*.tiff (assembled document)
    • manifest.json (metadata)
    • events.jsonl (event log)

Quick Troubleshooting

If scan fails:

  1. get_manifest({ job_id }) — check state and parameters
  2. get_events({ job_id }) — find error details in scanner_failed events
  3. Common fixes:
    • "No devices" → Ask user to check scanner power/connection
    • "Feeder jam" → Try { source: "Flatbed" }

For detailed troubleshooting, see TROUBLESHOOTING.md.

Reference Materials

  • TOOLS.md — Complete tool reference with all parameters
  • EXAMPLES.md — User intent → parameter mappings with reasoning
  • TROUBLESHOOTING.md — Detailed troubleshooting flows
  • CONFIG.md — Environment variables and configuration