ocrmypdf-mcp

A local Model Context Protocol (MCP) server that wraps OCRmyPDF, letting Claude Desktop (or any MCP client) add searchable text layers to scanned PDFs — with first-class support for batch-processing a Zotero library.

Everything runs locally. No documents leave your machine.

⚠️ Important: files are modified in place

By default, the OCR tools overwrite your original PDFs with the OCR'd version. This is intentional (so Zotero re-indexes the same attachment), but it means:

• Back up your PDFs (or your Zotero storage folder) before a large batch run.
• Use dry_run: true (supported by all three OCR tools) to preview what would be processed.
• Use the limit parameter of batch_ocr_folder for small trial runs before processing an entire library.

⚠️ Risk of PDF damage or data loss

Any tool that rewrites PDFs can, in rare cases, produce a broken or degraded file. Be aware of the following before running OCR over documents you cannot re-download:

• A rewritten PDF is a different file. Even in the safest mode the whole document is re-serialized. A malformed-but-viewable source PDF (some viewers tolerate damage that PDF libraries do not) may fail to convert, or convert with missing content. Files that OCRmyPDF cannot parse are reported as failed and left untouched — but verify a sample of outputs after a large batch.
• Interrupted runs: OCRmyPDF writes to a temporary file and only replaces the original on success, so a crash or forced shutdown mid-run should not corrupt the source — but do not kill the process while it is copying the final output into place.
• force=true is destructive. It rasterizes every page: existing text layers, vector graphics, and annotations are permanently replaced by a flat image plus new OCR text. Use it only on documents whose existing text layer is garbage.
• Wrong language = garbage text layer. OCR with a language that doesn't match the document produces nonsense text that then makes the file look "already searchable" to future runs.
• There is no undo. The tools do not keep backups. If the documents are irreplaceable, copy the folder first.

Tools

Tool	Description	Modifies files
check_needs_ocr	Report whether a PDF already has a searchable text layer	No
ocr_pdf	OCR a single PDF (in place, or to a new output path); supports dry_run	Yes
batch_ocr_folder	Start a background job that OCRs all PDFs under a folder, skipping ones that already have text; supports dry_run and limit	Yes
batch_status	Progress and per-file results of background jobs (or list all jobs)	No
cancel_batch	Stop a running background job before its next file	No
ocr_zotero_attachment	OCR the PDF(s) under a Zotero storage key, in place; supports dry_run	Yes

All tools follow the same rule: a PDF that already has a text layer is never touched. A PDF without one gets a text layer added while the original page images are preserved exactly (no deskew, no rotation, no recompression, no PDF/A conversion — unless you explicitly opt in via the deskew, rotate, or optimize parameters, which do alter the page images).

Prerequisites

What	Why	How to get it
Python 3.10+	Runs the server	python.org
Tesseract OCR 5.x	The OCR engine	Windows: winget install UB-Mannheim.TesseractOCR (the UB-Mannheim build); Linux: apt install tesseract-ocr; macOS: brew install tesseract
Tesseract language packs for every language you OCR	Wrong/missing packs produce garbage text	Select them in the Windows installer, or drop <lang>.traineddata files from tessdata_fast into Tesseract's tessdata folder (e.g. ces for Czech, deu for German, jpn + jpn_vert for Japanese)
Ghostscript	Used by OCRmyPDF for PDF rendering	Windows: winget install ArtifexSoftware.GhostScript
Python packages (mcp, ocrmypdf, pikepdf)	Server + PDF processing	pip install -r requirements.txt

Note: Tesseract cannot auto-detect document language — it only detects script/orientation. Set ocr_default_lang to a +-joined list matching your library (e.g. eng+ces), and pass language explicitly per call for outliers (e.g. jpn+jpn_vert). Keep the list short: every extra language slows OCR and increases misreads.

Tested with Python 3.12, OCRmyPDF 16.x, Tesseract 5.4, Ghostscript 10.x on Windows 11.

Installation

git clone https://github.com/chemysterium/ocrmypdf-mcp.git
cd ocrmypdf-mcp
pip install -r requirements.txt

Verify OCRmyPDF can find its dependencies:

ocrmypdf --version

Configuration

Copy the template and edit it with your paths:

cp config.example.json config.json

config.json (machine-specific, gitignored — never commit it):

{
  "zotero_storage": "C:\\Users\\<you>\\Zotero\\storage",
  "ocr_default_lang": "eng",
  "tesseract_path": "C:\\Program Files\\Tesseract-OCR"
}

Key	Meaning
zotero_storage	Root of your Zotero storage folder. Leave "" to disable the Zotero tool.
ocr_default_lang	Tesseract language code(s), +-joined: eng, eng+ces, eng+deu, … Requires matching Tesseract language packs.
tesseract_path	Folder containing the Tesseract executable. Leave "" to rely on your system PATH.

Settings can also be supplied (and are overridden) by environment variables: ZOTERO_STORAGE, OCR_DEFAULT_LANG, TESSERACT_PATH. To keep config.json somewhere else, point the OCRMYPDF_MCP_CONFIG env var at it.

Claude Desktop setup

Add to your claude_desktop_config.json (Settings → Developer → Edit Config), inside "mcpServers":

"ocrmypdf": {
  "command": "python",
  "args": ["C:\\path\\to\\ocrmypdf-mcp\\ocrmypdf_server.py"]
}

If Claude Desktop can't find python, use the full path to your interpreter. Restart Claude Desktop; four new tools should appear.

Usage examples

Ask Claude things like:

• "Check whether C:\scans\paper.pdf needs OCR."
• "Do a dry run of batch OCR on my Zotero storage folder and tell me how many files would be processed."
• "OCR the first 10 scanned PDFs in D:\archive, English plus Czech."
• "OCR the Zotero attachment AB12CD34 in place."

A sensible workflow for a large Zotero library:

1. batch_ocr_folder with dry_run: true, then poll batch_status → see the scope
2. batch_ocr_folder with limit: 5 → verify quality on a handful of files
3. Full run — start the job, then check batch_status occasionally (OCR is CPU-intensive; a large library can take hours)

Long runs and client timeouts

MCP clients abort tool calls that take too long — Claude Desktop's limit is about 60 seconds and is not configurable. Even scanning a large library for text layers can exceed that, let alone OCR-ing it.

batch_ocr_folder therefore returns immediately with a job_id while the work continues inside the server process. Poll batch_status for counters (scanned, processed, skipped, failed), the file currently being OCR'd, and recent per-file results. cancel_batch stops a job cleanly between files.

Notes:

• Jobs live in server memory. If the MCP client (and thus the server) restarts, the job stops — files already OCR'd keep their text layer, no file is left half-written (OCRmyPDF replaces files atomically on success), and you can simply start the batch again: already-processed files are skipped.
• ocr_pdf and ocr_zotero_attachment run synchronously. For a single normal-sized document they finish well within the timeout; a very large single PDF (hundreds of scanned pages) may exceed it — the client shows an error, but the OCR still completes in the background and the file gets its text layer.

How it decides what to skip

A PDF is considered "already searchable" if its content streams (including Form XObjects) contain a meaningful number of PDF text-show operators. This is a fast heuristic — a stray stamp, watermark, or publisher header won't count as a real text layer.

Files that pass the check are never opened for writing. Files that fail it are OCR'd in OCRmyPDF's redo_ocr mode, which handles mixed pages correctly: existing real text (e.g. a journal header on a scanned page) is kept, image regions get OCR text, and nothing is rasterized. If you enable deskew or rotate (incompatible with redo_ocr), the tool falls back to skip_text mode, which skips any page already containing text.

License

MIT — see LICENSE. OCRmyPDF itself is licensed under MPL-2.0 and is used here as an unmodified dependency.