Mistral OCR MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mistral OCR MCP Server OCR pages 0-3 of D:\docs\paper.pdf to markdown"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mistral OCR MCP Server
This MCP server exposes Mistral OCR for local files and public URLs.
Tools
Tool | Use |
| Validate keys, network access, model name, and output directory. |
| Set one runtime key for the current MCP process. |
| Set multiple runtime keys for automatic fallback. |
| Inspect a local file and return PDF page count when available. |
| OCR a local file and return Markdown inline. Best for short tests. |
| OCR a public URL and return Markdown inline. Best for short tests. |
| OCR a local file and save Markdown to disk. Best for PDFs. |
| 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.
Recommended Agent Workflow
Call
health_check.For a local PDF, call
list_pages.For a quick sample, call
ocr_from_filewithpages="0".For real work, call
ocr_to_markdown_fileand 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_KEYSaccepts comma-, semicolon-, or newline-separated keys.HTTP
401,403,429, selected transient failures, and5xxresponses trigger fallback to the next key.HTTP
400usually 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_DIRoroutputs/next toserver.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. Withinclude_images=true, the server requestsinclude_image_base64, writes image assets, and rewrites Markdown placeholders such asto local relative paths.
Available Tools
8 toolshealth_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
Scored across 8 tools
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 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.
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.
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
Related MCP Connectors
PDF, DOCX and image URLs to clean, LLM-ready Markdown or text, with OCR for scanned pages.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
PDF to Markdown and PDF to text from PDF URLs, page by page, with OCR for scanned pages
Convert scanned PDFs to Markdown or EPUB, and translate PDF and EPUB books via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceOCR images or pdfs, locally or by URLs by using Mistral OCR API (paid)40MIT
- AlicenseAqualityDmaintenanceConverts PDF files from local storage or URLs to structured Markdown format using Mistral AI's OCR API, preserving document structure and extracting images.21MIT
- FlicenseAqualityDmaintenanceExtracts text content from PDFs and images using Mistral's OCR API, enabling OCR capabilities in MCP-compatible clients like Cursor and Claude Desktop.18-
- AlicenseNot gradedqualityBmaintenanceConverts documents and images to Markdown using Mistral AI's OCR, enabling AI-powered document processing via MCP-compatible clients like Claude Desktop.62 npm2MIT