scan-mcp

Minimaler MCP-Server für Scanner-Erfassung (ADF/Duplex/Seitengröße), Stapelverarbeitung und mehrseitige Zusammenstellung.

Funktionen

• Kleiner, typisierter MCP-Server, der Werkzeuge für Geräteerkennung und Scan-Aufträge bereitstellt

• JSON-Schema-validierte Eingaben mit deterministischen, typisierten Ausgaben

• Intelligente Geräteauswahl (bevorzugt ADF/Duplex, vermeidet Kamera-Backends), robuste Standardwerte

• Lokale Transporte: standardmäßig stdio, um alles auf dem Gerät zu halten, optional HTTP für eigene Netzwerkbereitstellungen

Hinweis: Dieses Paket zielt auf Node 22 und Linux-SANE-Backends (scanimage).

Related MCP server: MCPOSprint

Schnellstart (lokales stdio, Standard)

Fügen Sie einen Server-Eintrag zu Ihrer MCP-Client-Konfiguration hinzu:

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

• Dieser Aufruf läuft über stdio für ein datenschutzorientiertes Einzelmaschinen-Setup.

• Rufen Sie start_scan_job ohne device_id auf, um automatisch einen Scanner auszuwählen und mit dem Scannen zu beginnen.

• Artefakte werden unter INBOX_DIR pro Auftrag geschrieben: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl. Wenn crop_carrier_sheets gesetzt ist und ein Trägerblatt erkannt wird, wird zusätzlich eine page_*.cropped.tiff-Derivatdatei für jede betroffene Seite geschrieben.

Streamable-HTTP-Transport

Möchten Sie den Scanner lieber an eine andere Maschine in Ihrem Netzwerk anschließen? scan-mcp unterstützt auch den streamable-HTTP-Transport:

scan-mcp --http

• Standardport ist 3001; setzen Sie MCP_HTTP_PORT, um ihn zu überschreiben (z. B. MCP_HTTP_PORT=3333 scan-mcp --http).

• Bindet standardmäßig an alle Schnittstellen (::); setzen Sie MCP_HTTP_HOST, um einzuschränken (z. B. MCP_HTTP_HOST=127.0.0.1, wenn ein Reverse-Proxy vor dem Server steht).

• HTTP-Antworten verwenden Server-Sent Events (SSE) für das Streaming von Werkzeugausgaben; Clients wie Claude Desktop und Windsurf unterstützen diesen Transport.

• Es gibt derzeit keine Authentifizierung; dies ist für interne LAN-Netzwerke gedacht.

Installation

• Mit npx ausführen: npx scan-mcp (empfohlen)

  • Die CLI führt einen schnellen Preflight-Check für Node 22+ und erforderliche Scanner-/Bildwerkzeuge durch und gibt Installationshinweise aus, wenn etwas fehlt.

  • Siehe empfohlene Server-Konfiguration oben.

• Verwenden Sie npx scan-mcp --http, um den streamable-HTTP-Transport zu starten, wenn Sie auf einer anderen Maschine laufen.

• CLI-Hilfe: scan-mcp --help

• Aus dem Quellcode (für Entwicklung):

  • npm install

  • npm run build

• Für Cline-Setup und andere automatisierte agentische Installationen siehe llms-install.md

Systemanforderungen

• Linux mit SANE-Dienstprogrammen: scanimage (und optional scanadf)

• TIFF-Werkzeuge: tiffcp (bevorzugt) oder ImageMagick convert

Umgebungsvariablen

• SCAN_MOCK (Standard: false): simuliert SANE-Aufrufe und generiert Fake-TIFFs für Tests.

• INBOX_DIR (Standard: scanned_documents/inbox): Basisverzeichnis für Auftragsläufe und Artefakte.

• SCANIMAGE_BIN / SCANADF_BIN (Standard: scanimage / scanadf): überschreibt Binärpfade.

• TIFFCP_BIN / IM_CONVERT_BIN (Standard: tiffcp / convert): Werkzeuge für mehrseitige Zusammenstellung.

• SCAN_EXCLUDE_BACKENDS (CSV): auszuschließende Backends (z. B. v4l).

• SCAN_PREFER_BACKENDS (CSV): bevorzugte Backends (z. B. epjitsu,epson2).

• PERSIST_LAST_USED_DEVICE (Standard: true): speichert und bevorzugt leicht das zuletzt verwendete Gerät.

• MCP_HTTP_PORT (Standard: 3001): TCP-Port für den HTTP-Transport.

API

Werkzeuge

• list_devices

  • Erkennt angeschlossene Scanner mit Backend-Details.

  • Eingaben: keine.

• get_device_options

  • Ruft SANE-Optionen für ein bestimmtes Gerät ab.

  • Eingaben:

    • device_id (Zeichenkette): Zielgerätekennung.

• start_scan_job

  • Startet einen Scan-Auftrag; das Weglassen von device_id löst automatische Auswahl und Standardoptionen aus.

  • Eingaben (alle optional, sofern nicht anders angegeben):

    • device_id (Zeichenkette)

    • resolution_dpi (Ganzzahl, 50–1200)

    • color_mode (Color | Gray | Lineart): color_mode standardmäßig Lineart (dokumentorientiert); bei >= 600 dpi standardmäßig Color, da hochauflösende Erfassung normalerweise Kunstwerke/Fotos bedeutet, bei denen 1-Bit Informationen zerstört. Übergeben Sie color_mode explizit, um beide Standardwerte zu überschreiben; hohe dpi ist das einzige verwendete Signal.

    • source (Flatbed | ADF | ADF Duplex)

    • duplex (boolesch)

    • 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 (Zeichenkette, Standard tiff)

    • tmp_dir (Zeichenkette)

    • crop_carrier_sheets (boolesch, Standard false): erkennt das vordere Randband von Trägerblättern und schreibt beschnittene Seiten-Derivate; Rohseiten werden beibehalten

• get_job_status

  • Untersucht Auftragsstatus und Artefaktanzahl.

  • Eingaben:

    • job_id (Zeichenkette)

• cancel_job

  • Fordert Auftragsabbruch an; bestmöglich während Scan-Schleifen.

  • Eingaben:

    • job_id (Zeichenkette)

• list_jobs

  • Listet aktuelle Aufträge aus dem Inbox-Verzeichnis auf.

  • Eingaben (optional):

    • limit (Ganzzahl, max. 100)

    • state (running | completed | cancelled | error | unknown)

• get_manifest

  • Ruft die manifest.json eines Auftrags ab.

  • Eingaben:

    • job_id (Zeichenkette)

• get_events

  • Ruft das events.jsonl-Protokoll eines Auftrags ab.

  • Eingaben:

    • job_id (Zeichenkette)

Siehe JSON-Schemas in schemas/ für Eingabeformen. Tests prüfen diese Verträge.

So funktionieren Auswahl und Standardwerte

Standardwerte zielen auf 300 dpi, angemessenen Farbmodus und ADF/Duplex, wenn verfügbar. Vollständige Details zu Bewertung und Fallbacks finden Sie in der Dokumentation:

• Auswahl und Standardwerte: docs/SELECTION.md

Projektstruktur

• src/mcp.ts — MCP-Server-Einstieg und Werkzeugregistrierung

• src/services/* — Hardware-Schnittstelle und Auftragsorchestrierung

• schemas/ — JSON-Schemas für Validierung und Tests

• docs/ — Architektur, Konventionen und tiefgehende Einblicke

Entwicklung

• npm run dev (stdio-MCP-Server), npm run dev:http (HTTP-Transport)

• make verify führt Lint, Typprüfung und Tests aus

• Konventionen: docs/CONVENTIONS.md und Architektur in docs/BLUEPRINT.md

Roadmap

Ideen und zukünftige Verbesserungen werden in docs/ROADMAP.md dokumentiert.