MCP server for OCR: AI agents read scans and ask before they run
Your agent calls six tools and gets a file back: text, Markdown, hOCR or JSON with a box and a confidence for every word. Which means: you see which words to check.
MCP server OCR tools: the six calls
| Tool | What it does |
|---|---|
list_pipelines | Lists pipelines with price per page in euros and formats, and names the default: the fastest and cheapest available one. |
quote | A dry run: page count and the price in euros in one plain sentence for the human. Without a named pipeline it uses the default and says so. Nothing runs, nothing is billed. |
submit_job | Starts a real job from the quote, only with the human's yes. It can wait for the result in the same call. |
job_status | State and counts of a job. done does not mean every page worked: check the failed and not-run counts. |
get_result | Fetches json, text, md, hocr or a searchable pdf into a file. |
uncertain_words | The words the OCR is least sure about, with confidence and position, so the agent checks them against the image. |
The README has the details of every tool.
A human confirms before the agent starts a job
The agent asks for a quote, a person looks at the page count and the price, and only then submit_job runs with human_confirmed=true. The person can name a pipeline; without one the quote names the default, never silently. The quoted price caps the cost: the job stops before a page that would exceed it. The call carries an Idempotency-Key, so a retry never creates a second job or a second charge. The rules for agents are in the agent guide, the calls in the API guide.
OCR results go to files, not into the chat
get_result writes the result to a file and returns the path, the size and a short check, never the whole content. Large documents do not fill the context of your agent. An existing file is never overwritten. A document is checked before it is sent: PDF, PNG, JPEG or TIFF, at most 100 MiB.
Install the OCR MCP server in Claude Desktop, Claude Code and Cursor
The source is public and MIT-licensed; the server needs Python 3.10 or newer. It is not on PyPI yet, so install it and the ocr-software client it builds on from GitHub, into a virtual environment:
python -m venv .venv
.venv/bin/pip install git+https://github.com/ocr-software/ocr-software-python git+https://github.com/ocr-software/ocr-software-mcp
On Windows the same lines use .venv\Scripts\pip. The path to that environment's Python goes into the configuration below. The server reads the hosted service with a key: get your API key.
Add this to claude_desktop_config.json and restart. The command is the Python of the virtual environment that holds the server.
{"mcpServers": {"ocr-software": {"command": "/path/to/.venv/bin/python",
"args": ["-m", "ocr_software_mcp"],
"env": {"OCR_KEY": "ocr_..."}}}}
claude mcp add ocr-software --env OCR_KEY=ocr_... -- /path/to/.venv/bin/python -m ocr_software_mcp
Use the same JSON as for Claude Desktop in .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects).
The key comes from the environment and never appears in a tool result. Do not paste it into the chat.
Run the OCR MCP server against your own server
The server also works against the package on your own server: set OCR_BASE_URL to its address, for example http://127.0.0.1:8080 (the install guide covers the server).
Production use, high volume or your own server?
Private use and tests are free. For a company in production, a server of your own or a pipeline built on your pages, send the kind of page and the volume, and get a written offer.
