OCR-MCP

Complete AI OCR webapp and MCP server. A web app with a streamlined dashboard (drag-and-drop or scanner, pick an engine, click one button) and a FastMCP 3.1 MCP server for agentic IDEsClaude, Cursor, Windsurfso agents can run OCR, preprocessing, and workflows as tools. Same 14 engines, WIA scanner (Windows), and pipelines; one repo.

Topics: ocr, mcp, fastmcp, document-processing, scanner, wia, pdf, computer-vision, model-context-protocol, llm

What it does

• Web app React (web_sota/) + FastAPI (backend/app.py): upload or scan, pick engine, get text/PDF/JSON. Ports 10858 (Vite) and 10859 (API). In-app Help (/help) documents the web UI, the MCP server, and OCR backends.
• MCP server FastMCP 3.1 stdio: tools for OCR, preprocessing, scanner, workflows. Sampling defaults to local Ollama (http://127.0.0.1:11434/v1, model llama3.2) no cloud API key. Set OCR_SAMPLING_USE_CLIENT_LLM=1 to use the host IDEs LLM instead. Mistral OCR uses MISTRAL_API_KEY when you call that backend. See AI_FEATURES.md.

Features: 14 backends (Unlimited-OCR, PaddleOCR-VL-1.5, Nemotron VL 8B, DeepSeek-OCR-2, MinerU2.5-Pro, Mistral OCR) Auto backend selection Preprocessing (deskew, enhance, crop) Layout & table extraction Form detection & reconstruction (checkbox, text field, radio, signature detection → fillable ODT via libreoffice-mcp) Quality assessment WIA scanner Auto-Scan watcher (detect documents on flatbed, auto-OCR) Batch & pipelines Multi-format export

Docs

Doc	Description
Install	Install, run MCP, Web UI (start.ps1, ports 10858/10859), PyYAML notes, client config
Recent improvements	Incremental improvements log, newest first: backends, UI, hygiene
Backend deps	Web FastAPI backend: same venv as ocr-mcp, pyproject.toml, PyTorch, OCR_AUTO_INSTALL_DEPS
Technical	Architecture, tools, config, development, packaging
OCR models	Engines, capabilities, hardware (see also AI_MODELS.md)
Backend requirements	Per-model pip packages, system deps, env/config
MCP toolset matrix	Portmanteau tools, operation status, corpus v0
AI features	Sampling, SEP-1577, agentic workflows, prompts

Also: JUSTFILE.md (just recipes) OCR-MCP_MASTER_PLAN.md (roadmap) tests/README.md (testing)

Quick Start

git clone https://github.com/sandraschi/ocr-mcp
cd ocr-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

🛡️ Industrial Quality Stack

This project adheres to SOTA 14.1 industrial standards for high-fidelity agentic orchestration:

• Python (Core): Ruff for linting and formatting. Zero-tolerance for print statements in core handlers (T201).
• Webapp (UI): Biome for sub-millisecond linting. Strict noConsoleLog enforcement.
• Protocol Compliance: Hardened stdout/stderr isolation to ensure crash-resistant JSON-RPC communication.
• Automation: Justfile recipes for all fleet operations (just lint, just fix, just dev).
• Security: Automated audits via bandit and safety.

Install (Claude Desktop)

irm https://github.com/sandraschi/ocr-mcp/releases/latest/download/install.ps1 | iex

Or download ocr-mcp.mcpb from releases (stable name) and install it in Claude Desktop. Other clients (Cursor, Windsurf, opencode):

{
  "mcpServers": {
    "ocr-mcp": {
      "command": "uv",
      "args": ["--directory", "D:/Dev/repos/ocr-mcp", "run", "ocr-mcp"]
    }
  }
}

Stack

Layer	Tech
MCP server	Python 3.12+, FastMCP 3.4 (stdio + streamable HTTP), Pydantic v2
REST backend	FastAPI + Uvicorn (backend/app.py, port 10859)
Web UI	React + Vite + TypeScript + TailwindCSS + Zustand + Lucide + Framer Motion (web_sota/, port 10858)
Desktop	Tauri 2.0 NSIS (native/)
Lint/type	Ruff (T20), Pyright, Biome, tsc

MCP tools (portmanteau)

Tool	Operations
process_document	process_document, process_batch, analyze_layout, extract_tables, detect_forms, analyze_reading_order, classify_type, extract_metadata, assess_quality, validate_accuracy, compare_backends, analyze_image_quality
manage_image	preprocess, convert, pdf_to_images, embed_text
operate_scanner	list_scanners, scanner_properties, configure_scan, scan_document, scan_batch, preview_scan, diagnostics
manage_workflow	process_batch_intelligent, create/execute/monitor pipeline, optimize_processing, ocr_health_check, list_backends, manage_models
manage_corpus	register, update_metadata, get, search, list_recent, attach_ocr_result
ingest_book	detect_chapters, detect_metadata, assemble_epub, full_pipeline
execute_agentic_workflow	goal-driven multi-step OCR via sampling (SEP-1577)
llm_ops	list_models, loaded, switch_model, unload_all, vram
get_help / get_status / shutdown_server	docs, health, graceful exit

Env vars

Var	Default	Purpose
OCR_DEFAULT_BACKEND	auto	default engine (tesseract, paddleocr-vl, mistral-ocr, …)
MISTRAL_API_KEY	—	Mistral OCR cloud backend
OCR_TRANSPORT / MCP_TRANSPORT	stdio	stdio, http, sse
MCP_PORT / OCR_PORT	10859	HTTP bind port
TESSERACT_CMD / POPPLER_PATH	—	native helper paths (Windows)
OCR_SAMPLING_USE_CLIENT_LLM	0	1 = use host IDE LLM for sampling

Ports

Service	Port
Vite frontend	10858
FastAPI backend + MCP HTTP (/mcp)	10859

Full reference: llms-full.txt. Backend deps: docs/BACKEND_DEPS.md. Onboarding: docs/ONBOARDING.md.

License

MIT — see LICENSE.