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

Five tools, each one API call. The API itself is described in the API guide, the rules for agents in the agent guide.

job_budget is the most the job may cost, as a whole number of millicents (1 EUR = 100000); the job stops before a page that would exceed it. If the operator set no prices, it has no effect, but the tool still requires a whole number of at least 1.

Retries follow the agent guide: 429, 500, 503 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.

Related MCP server: PennyOCR

Settings

Environment variables only.

Safety rules built in

• The agent cannot start a paid job without human_confirmed, and the budget caps the cost: the job stops before a page that would exceed job_budget.

• 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.

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 the monorepo the ocr-software package is found next to this folder):

python -m venv .venv && .venv/bin/pip install mcp==1.30.0 pytest
.venv/bin/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