Skip to main content
Glama
Mistral OCR MCP Server

Mistral OCR MCP Server

by uuina

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.

Related MCP server: MCP-PDF2MD

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.

  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.

Available Tools

8 tools
health_checkA

Check MCP configuration, key validity, output directory, and model name.

Inputs: no named parameters. Returns: result

list_pagesB

Return basic local file information and PDF page count when available.

Inputs: file_path (required). Returns: result

ocr_from_fileA

从本地文件或图片中提取 Markdown 文本并以字符串形式返回。

默认使用 "mistral-ocr-latest" 模型。
默认不提取图片。若需提取,需设置 include_images=True。

可调参数:
- file_path (str): 必填,本地文档(如 PDF, PPTX, DOCX)或图片文件的绝对路径。
- pages (str, 默认 ""): 指定需要提取的页码范围(如 "0-3"),为空表示提取所有页面。
- table_format (str, 默认 "markdown"): 表格输出格式。可选 "markdown"、"html" 或 None。
- include_images (bool, 默认 False): 是否提取图片。若开启,将返回图片信息。
- extract_header (bool, 默认 False): 是否专门解析并提取页眉。
- extract_footer (bool, 默认 False): 是否专门解析并提取页脚。
- image_limit (int, 默认 0): 限制单次提取的最大图片数量。
- image_min_size (int, 默认 0): 设置提取图片的最小尺寸限制(像素)。

Inputs: file_path (required), pages, image_limit, table_format, +4 more. Returns: result

ocr_from_urlB

从公开的文档或图片 URL 中提取 Markdown 文本。

默认使用 "mistral-ocr-latest" 模型。
默认不提取图片。若需提取,需设置 include_images=True。

可调参数:
- url (str): 必填,目标文件或图片的公网 URL 地址。
- pages (str, 默认 ""): 指定需要提取的页码范围(如 "0-3"),为空表示提取所有页面。
- table_format (str, 默认 "markdown"): 表格输出格式。可选 "markdown"、"html" 或 None。
- include_images (bool, 默认 False): 是否提取图片。若开启,将返回图片信息。
- extract_header (bool, 默认 False): 是否专门解析并提取页眉。
- extract_footer (bool, 默认 False): 是否专门解析并提取页脚。
- image_limit (int, 默认 0): 限制单次提取的最大图片数量。
- image_min_size (int, 默认 0): 设置提取图片的最小尺寸限制(像素)。

Inputs: url (required), pages, image_limit, table_format, +4 more. Returns: result

ocr_to_markdown_fileA

OCR 本地文件并将生成的 Markdown 保存至磁盘。

默认使用 "mistral-ocr-latest" 模型。
默认不提取图片。若需提取,需设置 include_images=True。
非常适用于 PDF 或较长文档的 OCR,以避免因结果过大而超出模型上下文窗口限制。

可调参数:
- file_path (str): 必填,本地文档(如 PDF, PPTX, DOCX)或图片文件的绝对路径。
- pages (str, 默认 ""): 指定需要提取的页码范围(如 "0-3"),为空表示提取所有页面。
- output_dir (str, 默认 ""): 指定保存 Markdown 文件的目录路径,若为空则使用默认输出目录。
- table_format (str, 默认 "markdown"): 表格输出格式。可选 "markdown"、"html" 或 None。
- include_images (bool, 默认 False): 是否提取图片。若开启,将返回并保存图片信息。
- extract_header (bool, 默认 False): 是否专门解析并提取页眉。
- extract_footer (bool, 默认 False): 是否专门解析并提取页脚。
- use_cache (bool, 默认 True): 是否启用缓存,已处理过的内容直接返回缓存路径。
- image_limit (int, 默认 0): 限制单次提取的最大图片数量。
- image_min_size (int, 默认 0): 设置提取图片的最小尺寸限制(像素)。

Inputs: file_path (required), pages, use_cache, output_dir, +6 more. Returns: result

ocr_url_to_markdown_fileA

OCR 公网 URL 指向的文件并将生成的 Markdown 保存至磁盘。

默认使用 "mistral-ocr-latest" 模型。
默认不提取图片。若需提取,需设置 include_images=True。

可调参数:
- url (str): 必填,目标文件或图片的公网 URL 地址。
- pages (str, 默认 ""): 指定需要提取的页码范围(如 "0-3"),为空表示提取所有页面。
- output_dir (str, 默认 ""): 指定保存 Markdown 文件的目录路径,若为空则使用默认输出目录。
- table_format (str, 默认 "markdown"): 表格输出格式。可选 "markdown"、"html" 或 None。
- include_images (bool, 默认 False): 是否提取图片。若开启,将返回并保存图片信息。
- extract_header (bool, 默认 False): 是否专门解析并提取页眉。
- extract_footer (bool, 默认 False): 是否专门解析并提取页脚。
- use_cache (bool, 默认 True): 是否启用缓存,已处理过的内容直接返回缓存路径。
- image_limit (int, 默认 0): 限制单次提取的最大图片数量。
- image_min_size (int, 默认 0): 设置提取图片的最小尺寸限制(像素)。

Inputs: url (required), pages, use_cache, output_dir, +6 more. Returns: result

set_api_keyC

Set one Mistral API key for this running MCP server.

Inputs: api_key (required). Returns: result

set_api_keysC

Set one or more Mistral API keys for this running MCP server.

Args:
    api_keys: Comma-, semicolon-, or newline-separated API keys.

Inputs: api_keys (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes: health_check, list_pages, and API key management are clearly separate. The four OCR tools form two pairs (from_file vs from_url, and return string vs save to file), which are distinguishable by source and output, but could cause confusion if an agent overlooks the output difference.

    Naming Consistency3/5

    Naming uses a mix of patterns: 'ocr_from_file' vs 'ocr_to_markdown_file' use different prepositions for source vs destination, while 'set_api_key' and 'set_api_keys' are consistent. Overall, the names are readable but not perfectly consistent.

    Tool Count5/5

    8 tools cover the essential functions: health check, file listing, two OCR sources, two output options, and API key management. This is well-scoped for an OCR server without being excessive.

    Completeness4/5

    The tool set covers all core OCR operations (from file and URL, output as string or file) plus configuration and key management. Minor gaps exist, such as no direct model selection or cache clearing, but the main workflow is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers