# 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
  `![img-0.jpeg](img-0.jpeg)` to local relative paths.