OCR MCP server for ocr-software.com: let Claude, Cursor and other agents read PDFs and scans

Give your AI agent a way to read documents: this MCP server sends PDF, PNG, JPEG and TIFF files to the ocr-software.com OCR API and writes the result (JSON with word boxes, text, Markdown or hOCR) to a file. The API is hosted in Helsinki, EU (Hetzner). It also works against the package on your own server, which takes the same calls: set OCR_BASE_URL to its address (install guide).

The server is small and strict by design. A person picks the pipeline, sees the page count first, and says yes before anything runs. More on the idea and on what to expect: OCR for AI agents (MCP).

Tools

Six tools. The API itself is described in the API guide, the rules for agents in the agent guide. The normal path is three calls: list_pipelines, quote, submit_job with wait_seconds and format.

verified (per word) and safe_ok (per page) in the JSON result are flags of the OCR service, not of this server. verified is true when a second reader confirmed the word: scan-vlm-ctc@2 sets it where the character reader read the same text (flag ok); the other pipelines have one reader and leave it false. safe_ok is always false today (not calibrated), which says nothing against the page. Judge a word by confidence (0 to 1) and flag. box is [x0, y0, x1, y1] in pixels of the page image, origin top left; the page's width, height and dpi say which image, and PDF points are pixels * 72 / dpi. uncertain_words lists words with confidence below 0.9 (the really wrong words of the gold set sat at about 0.83) or a differing second reading.

Price: the API counts in millicents (100,000 millicents = 1 EUR); this server speaks euros. Today nothing is charged: quote says "you pay EUR 0.00 today", shows the list price for information and names the fair-use rules (https://ocr-software.com/legal/fair-usage/) and info@ocr-software.com for more volume.

The job budget is internal: quote gives the price in the plain sentence, the server sends the quoted price as the cap, and the job stops before a page that would exceed it. If the operator set no prices, no cap is sent.

Retries follow the agent guide: 429, 500, 502, 503, 504 and network errors up to 5 times with growing waits. A Retry-After over 60 seconds goes back to the human at once. Other 4xx errors are never retried.

Settings

Environment variables only.

Safety rules built in

• The agent cannot start a job without a quote_id and a yes of the human, and the quoted price caps the cost: the job stops before a page that would exceed it. A file that changed since the quote is refused.
• Every document is checked locally before it is sent: PDF, PNG, JPEG or TIFF by its first bytes, a regular file, at most 100 MiB.
• Results go to files, not into the conversation, so large documents do not fill the context.
• The key is read from the environment and never appears in a tool result.

Install

Python 3.10 or newer. The package ocr-software-mcp runs the server (it needs the ocr-software package, installed with it).

uvx ocr-software-mcp            # run without installing (uv)
pipx install ocr-software-mcp   # or install once; the command is then ocr-software-mcp
pip install ocr-software-mcp    # inside a venv

Claude Desktop

Add this to claude_desktop_config.json, then restart. The file is in ~/Library/Application Support/Claude/ on macOS and in %APPDATA%\Claude\ on Windows:

{"mcpServers": {"ocr-software": {"command": "uvx", "args": ["ocr-software-mcp"],
                                 "env": {"OCR_KEY": "ocr_..."}}}}

With pipx use "command": "ocr-software-mcp" and no args.

On Windows, uv must be on the PATH that Claude Desktop sees (install it with winget install astral-sh.uv, then restart Claude Desktop); otherwise use pipx and "command": "ocr-software-mcp".

Claude Code

claude mcp add ocr-software --env OCR_KEY=ocr_... -- uvx ocr-software-mcp

Cursor

Use the same JSON as for Claude Desktop in .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects).

Your own server

"env": {"OCR_KEY": "ocr_...", "OCR_BASE_URL": "http://127.0.0.1:8080"}

The names OCR_SOFTWARE_API_KEY, OCR_SOFTWARE_BASE_URL and OCR_SOFTWARE_ALLOWED_DIR of the ocr-software package and its CLI are read too; the OCR_ names above win if both are set.

Tests

A fake local service, no network and no key needed. In a fresh clone, install the package with its test extra (this brings mcp and ocr-software), then run pytest:

python -m venv .venv
.venv/bin/pip install -e ".[test]"            # Windows: .venv\Scripts\pip install -e ".[test]"
.venv/bin/python -m pytest -p no:cacheprovider .    # Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .

License

MIT, see LICENSE. More about the service, its pipelines and output formats: ocr-software.com.

Provider and legal

The OCR runs on the ocr-software.com API, operated by Helm & Nagel GmbH. Terms · Privacy · Imprint · Security

mcp-name: io.github.ocr-software/ocr-software-mcp