Mistral OCR MCP Server

This MCP server exposes Mistral OCR for local files and public URLs.

Tools

Tool	Use
health_check	Validate keys, network access, model name, and output directory.
set_api_key	Set one runtime key for the current MCP process.
set_api_keys	Set multiple runtime keys for automatic fallback.
list_pages	Inspect a local file and return PDF page count when available.
ocr_from_file	OCR a local file and return Markdown inline. Best for short tests.
ocr_from_url	OCR a public URL and return Markdown inline. Best for short tests.
ocr_to_markdown_file	OCR a local file and save Markdown to disk. Best for PDFs.
ocr_url_to_markdown_file	OCR a public URL and save Markdown to disk.

Configuration

Prefer multiple keys so the server can automatically switch when one key is unauthorized, rate-limited, or temporarily failing.

[mcp_servers.mistral-ocr]
type = "stdio"
command = "uv"
args = ["--directory", 'D:\34728\play\OCR\mistral-ocr-mcp', "run", "server.py"]

[mcp_servers.mistral-ocr.env]
MISTRAL_API_KEYS = "key1,key2,key3"
MISTRAL_OCR_OUTPUT_DIR = 'D:\34728\play\OCR\outputs'

Single-key compatibility is still supported:

MISTRAL_API_KEY = "key1"

After editing the Codex config, restart Codex or reload MCP tools so the new server process sees the environment variables.

Recommended Agent Workflow

1. Call health_check.
2. For a local PDF, call list_pages.
3. For a quick sample, call ocr_from_file with pages="0".
4. For real work, call ocr_to_markdown_file and read the generated .md.

Example:

health_check()
list_pages(file_path="D:\docs\paper.pdf")
ocr_to_markdown_file(file_path="D:\docs\paper.pdf", pages="0-3")

To preserve extracted PDF figures, pass include_images=true.

ocr_to_markdown_file(
  file_path="D:\docs\paper.pdf",
  pages="0-5",
  include_images=true,
  image_limit=50,
  image_min_size=64
)

The Markdown file will contain relative image links and the image files will be saved in a sibling folder named like paper_hash_assets/.

Local Smoke Tests

cd D:\34728\play\OCR\mistral-ocr-mcp
uv sync
$env:MISTRAL_API_KEYS="key1,key2"
.\.venv\Scripts\python.exe -m py_compile server.py test_ocr.py
.\.venv\Scripts\python.exe test_ocr.py "https://arxiv.org/pdf/2201.04234"

Notes

• MISTRAL_API_KEYS accepts comma-, semicolon-, or newline-separated keys.
• HTTP 401, 403, 429, selected transient failures, and 5xx responses trigger fallback to the next key.
• HTTP 400 usually means a bad request or unsupported file payload and does not trigger key rotation.
• Saved Markdown uses UTF-8 and is written to MISTRAL_OCR_OUTPUT_DIR or outputs/ next to server.py.
• Cache filenames include a content/options hash. Re-running the same OCR task returns the cached Markdown path unless use_cache=false.
• Mistral OCR returns images separately from Markdown. Without include_images=true, the server saves text/tables only. With include_images=true, the server requests include_image_base64, writes image assets, and rewrites Markdown placeholders such as ![img-0.jpeg](img-0.jpeg) to local relative paths.