Content
# 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.
```toml
[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:
```toml
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:
```text
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`.
```text
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
```powershell
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
`` to local relative paths.
