How do I use Mistral OCR MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mistral OCR MCP Server extract markdown from /Users/me/documents/report.pdf" 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

by ORDIS-Co-Ltd

Overview Schema Source Related Servers Discussions Admin

Python

Local

Mistral OCR MCP Server

A Model Context Protocol (MCP) server that provides tools for extracting text and images from PDF and image files using the Mistral OCR API.

Features

Local & URL Extraction: Extract markdown from local files or remote URLs
Image Handling on Demand: Optionally save embedded images to disk with proper relative links
Advanced OCR: Page selection, table format control, model selection
Health Check: Built-in API status endpoint
Security Sandbox: Restricts file writes to a configured allowed directory
Zero-Install Deployment: Run with uvx without prior installation
Supported Formats: PDF (.pdf), PNG (.png), JPEG (.jpg, .jpeg), WebP (.webp), GIF (.gif)

Related MCP server: MCP-PDF2MD

Client Configuration

Claude Desktop

Add this to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mistral-ocr": {
      "command": "uvx",
      "args": ["mistral-ocr-mcp"],
      "env": {
        "MISTRAL_API_KEY": "your-api-key-here",
        "MISTRAL_OCR_ALLOWED_DIR": "/absolute/path/to/allowed/directory"
      }
    }
  }
}

OpenCode

Add this to the mcp section of your configuration file:

{
  "mcp": {
    "mistral-ocr": {
      "type": "local",
      "command": ["uvx", "mistral-ocr-mcp"],
      "enabled": true,
      "environment": {
        "MISTRAL_API_KEY": "your-api-key-here",
        "MISTRAL_OCR_ALLOWED_DIR": "/absolute/path/to/allowed/directory"
      }
    }
  }
}

Codex

If you use the Codex CLI, you can add the server with:

codex mcp add mistral-ocr -- uvx mistral-ocr-mcp

Make sure the environment variables MISTRAL_API_KEY and MISTRAL_OCR_ALLOWED_DIR are set in your shell environment.

Configuration

Required Environment Variables

Variable	Description	Example
`MISTRAL_API_KEY`	Your Mistral API key (never logged)	`sk-abc123...`
`MISTRAL_OCR_ALLOWED_DIR`	Absolute path to allowed write directory	`/Users/username/workdir`

Security Sandbox

The server enforces a write directory sandbox to prevent unauthorized file writes. When include_images is True, the output_dir parameter must be within MISTRAL_OCR_ALLOWED_DIR. Text-only extraction (include_images=False) is read-only and has no sandbox restrictions.

Validation Examples:

`MISTRAL_OCR_ALLOWED_DIR`	`output_dir`	Result
`/Users/username/workdir`	`/Users/username/workdir/project/output`	✅ Allowed
`/Users/username/workdir`	`/Users/username/workdir`	✅ Allowed (exact match)
`/Users/username/workdir`	`/Users/username/documents`	❌ Rejected
`/Users/username/workdir`	`/Users/username/workdir/../documents`	❌ Rejected (resolves outside)

Security Notes:

All paths are canonicalized (symlinks resolved, .. eliminated) before validation
Image filenames are sanitized to prevent path traversal attacks

Tool Reference

Tool 1: `extract_markdown`

Extract markdown from a local file, optionally saving embedded images to disk.

Arguments:

Parameter	Type	Required	Default	Description
`file_path`	`string`	Yes	—	Absolute path to input file (PDF or image)
`output_dir`	`string`	No	`null`	Absolute path to output parent directory. Required when `include_images` is `True`.
`include_images`	`boolean`	No	`false`	When `True` and `output_dir` is set, saves images to disk

Returns (text-only):

{"result": "# Document Title\n\nExtracted markdown content..."}

Returns (with images):

{
  "output_directory": "/absolute/path/to/output/report",
  "markdown_file": "/absolute/path/to/output/report/content.md",
  "images": ["img_abc123.png", "img_def456.jpeg"]
}

Behavior (with images):

Creates a subdirectory named after the input file stem (e.g., report for report.pdf)
If the subdirectory already exists, appends a timestamp: report_20260102_143022
Saves all extracted images as <sanitized_id>.<ext> (e.g., img_abc123.png)
Saves markdown to content.md with relative image links (e.g., ![](./img_abc123.png))

Output Structure:

/Users/username/workdir/extracted/
  quarterly-report/
    content.md          # Markdown with relative image links
    img_abc123.png      # First extracted image
    img_def456.jpeg     # Second extracted image

Tool 2: `extract_markdown_from_url`

Extract markdown from a publicly accessible URL, optionally saving embedded images to disk.

Arguments:

Parameter	Type	Required	Default	Description
`file_url`	`string`	Yes	—	Public URL to a PDF or image
`output_dir`	`string`	No	`null`	Absolute path to output parent directory. Required when `include_images` is `True`.
`include_images`	`boolean`	No	`false`	When `True` and `output_dir` is set, saves images to disk

Returns (text-only):

{"result": "# Document Title\n\nExtracted markdown content..."}

Returns (with images):

{
  "output_directory": "/absolute/path/to/output/doc",
  "markdown_file": "/absolute/path/to/output/doc/content.md",
  "images": ["img_abc123.png"]
}

Tool 3: `extract_markdown_advanced`

Extract markdown with advanced OCR options.

Arguments:

Parameter	Type	Required	Default	Description
`file_path`	`string`	Yes	—	Absolute path to input file (PDF or image)
`pages`	`array[integer]`	No	`null`	Page numbers to process (1-indexed, e.g. `[1, 3, 5]`)
`table_format_`	`string`	No	`null`	Table output format (`"markdown"` or `"html"`)
`model`	`string`	No	`"mistral-ocr-latest"`	OCR model to use

Returns:

{"result": "# Document\n\n| Col 1 | Col 2 |\n|-------|-------|\n..."}

Tool 4: `ocr_status`

Check API connectivity and key validity.

Arguments: none

Returns:

{
  "status": "ok",
  "message": "API key is working"
}

Example Client Usage

Here's a minimal Python example using the MCP SDK to call the tools:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def extract_document():
    server_params = StdioServerParameters(
        command="mistral-ocr-mcp",
        env={
            "MISTRAL_API_KEY": "your-api-key",
            "MISTRAL_OCR_ALLOWED_DIR": "/Users/username/workdir"
        }
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Text-only extraction
            result = await session.call_tool(
                "extract_markdown",
                arguments={"file_path": "/path/to/document.pdf"}
            )
            print(result.content[0].text)
            
            # Extraction with images
            result = await session.call_tool(
                "extract_markdown",
                arguments={
                    "file_path": "/path/to/document.pdf",
                    "include_images": True,
                    "output_dir": "/Users/username/workdir/output"
                }
            )
            print(result.content[0].text)
            
            # Extract from URL
            result = await session.call_tool(
                "extract_markdown_from_url",
                arguments={"file_url": "https://example.com/doc.pdf"}
            )
            print(result.content[0].text)
            
            # Check API status
            result = await session.call_tool("ocr_status", arguments={})
            print(result.content[0].text)

asyncio.run(extract_document())

Troubleshooting

Error	Cause	Solution
`Missing required environment variable: MISTRAL_API_KEY`	`MISTRAL_API_KEY` not set	Set the environment variable before running the server
`Missing required environment variable: MISTRAL_OCR_ALLOWED_DIR`	`MISTRAL_OCR_ALLOWED_DIR` not set	Set the environment variable to an absolute path
`MISTRAL_OCR_ALLOWED_DIR must be an absolute path`	Relative path provided (e.g., `~/documents`)	Use an absolute path (e.g., `/Users/username/documents`)
`MISTRAL_OCR_ALLOWED_DIR does not exist`	Directory does not exist on filesystem	Create the directory first: `mkdir -p /path/to/dir`
`MISTRAL_OCR_ALLOWED_DIR is not a directory`	Path points to a file, not a directory	Ensure the path is a directory
`validate file_path: must be an absolute path: {path}`	Relative path provided for input file	Use an absolute path (e.g., `/Users/username/file.pdf`)
`validate file_path: resolve failed, path does not exist: {path}`	Input file does not exist	Check the file path and ensure the file exists
`validate file_path: unsupported file type '{suffix}'. Supported types: ...`	File extension not supported	Use `.pdf`, `.png`, `.jpg`, `.jpeg`, `.webp`, or `.gif`
`validate output_dir: resolve failed, path does not exist: {path}`	Output directory does not exist	Create the directory first: `mkdir -p {path}`
`validate output_dir: path is not a directory: {path}`	Path points to a file, not a directory	Ensure the path is a directory
`validate output_dir: writability check failed, directory not writable: {path}`	Output directory exists but is not writable	Check directory permissions: `chmod u+w {path}`
`output_dir must be within the allowed directory`	`output_dir` is outside `MISTRAL_OCR_ALLOWED_DIR`	Use a path within the allowed directory
`Mistral OCR request failed (status=401): {message}`	Invalid API key	Check your `MISTRAL_API_KEY`
`Mistral OCR request failed (status=429): {message}`	Rate limit exceeded	Wait and retry, or check your API quota

Development

Setup

Clone the repository and install with development dependencies:

git clone https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
cd mistral-ocr-mcp
pip install -e '.[dev]'

Run the server locally:

MISTRAL_API_KEY="your-key" \
MISTRAL_OCR_ALLOWED_DIR="/path/to/allowed/dir" \
python -m mistral_ocr_mcp

Run Tests

pytest

Project Structure

mistral-ocr-mcp/
├── src/
│   └── mistral_ocr_mcp/
│       ├── __init__.py
│       ├── __main__.py          # Entry point
│       ├── server.py            # MCP server and tool definitions
│       ├── config.py            # Configuration loading and validation
│       ├── extraction.py        # OCR orchestration logic
│       ├── mistral_client.py    # Mistral API client
│       ├── images.py            # Image parsing and saving
│       ├── markdown_rewrite.py  # Markdown link rewriting
│       └── path_sandbox.py      # Path validation and sandbox enforcement
├── tests/                       # Unit tests
├── pyproject.toml              # Package configuration
└── README.md                   # This file

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Available Tools

4 tools

extract_markdownA

Extract markdown text from a PDF or image file.

When output_dir is provided, saves the extracted markdown to content.md inside a named subdirectory. When include_images is also True, saves embedded images alongside the markdown file. Otherwise returns the markdown text inline.

Args: file_path: Absolute path to the input file (PDF or image) output_dir: Absolute path to an existing output directory (must be within allowed dir). When set, saves markdown to disk at <output_dir>/<file_stem>/content.md. include_images: When True (requires output_dir), save images to disk and rewrite markdown with relative image links.

Returns: When output_dir is not set: result: Extracted markdown content When output_dir is set (with or without images): output_directory: Absolute path to the output subdirectory markdown_file: Absolute path to the content.md file images: List of saved image filenames (empty if include_images is False)

Inputs: file_path (required), output_dir, include_images. Returns: images, result, markdown_file, output_directory

extract_markdown_advancedA

Extract markdown with advanced OCR options.

Args: file_path: Absolute path to the input file (PDF or image) pages: Specific page numbers to process (1-indexed, e.g. [1, 3, 5]) table_format_: Output format for tables ("markdown" or "html") model: OCR model to use (default: "mistral-ocr-latest")

Returns: Extracted markdown content as a string

Inputs: file_path (required), model, pages, table_format_. Returns: result

extract_markdown_from_urlA

Extract markdown text from a publicly accessible URL.

Processes a PDF or image directly from a URL without uploading a local file first. When output_dir is provided, saves the extracted markdown to content.md inside a named subdirectory. When include_images is also True, saves embedded images alongside the markdown file.

Args: file_url: Publicly accessible URL to a PDF or image output_dir: Absolute path to an existing output directory (must be within allowed dir). When set, saves markdown to disk at <output_dir>/<url_stem>/content.md. include_images: When True (requires output_dir), save images to disk and rewrite markdown with relative image links.

Inputs: file_url (required), output_dir, include_images. Returns: images, result, markdown_file, output_directory

ocr_statusA

Check Mistral API connectivity and key validity.

Makes a lightweight API call to verify the configured API key is working correctly.

Returns: Dictionary with status ("ok" or "error") and message

Inputs: no named parameters. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-08-08 06:25 across 4 tools

Disambiguation4/5

extract_markdown and extract_markdown_advanced both process local files with overlapping functionality, but the 'advanced' variant clearly adds page selection and table formatting options; extract_markdown_from_url is distinct by input source, and ocr_status is clearly separate. Mostly distinct with one potential confusion.

Naming Consistency4/5

Three tools follow the verb_noun pattern (extract_markdown, extract_markdown_from_url, extract_markdown_advanced), but ocr_status deviates by using a noun phrase instead of an action verb, creating minor inconsistency.

Tool Count5/5

Four tools cover the core OCR extraction workflows (local file, URL, advanced options) plus a connectivity check, making a well-scoped and appropriate set for this server.

Completeness4/5

The server covers the primary extraction methods and includes advanced options for page selection and table format. Minor gaps exist such as no batch processing or format listing, but core workflows are complete.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

PDF to Markdown & Document Parser
io.github.fernandoguiraud16-coder
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
RAG Systems Data Platforms
1
https://mcp.apify.com/?tools=fguiraud/document-to-markdown-tables
FrenchieA
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
https://mcp.getfrenchie.dev
doc-convert-mcpA
dev.ioconnex
Document conversion and OCR for AI agents: PDF, Office docs, images to text.
Image & Video Processing AI & Machine Learning
41
https://convert.ioconnex.dev/mcp
PDF & Office to Markdown for RAG
io.github.BrunenJere
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
RAG Systems Data Platforms
1
https://mcp.apify.com/?tools=lif_manager/documents-to-markdown-rag

Related MCP Servers

mcp-mistral-ocr
Image & Video Processing App Automation
everaldo
A
license
Not graded
quality
D
maintenance
OCR images or pdfs, locally or by URLs by using Mistral OCR API (paid)
Updated 9 months ago (2026-02-21 11:50 UTC)
40
MIT
MCP-PDF2MD
File Systems Documentation Access App Automation
zicez
A
license
A
quality
D
maintenance
Converts PDF files from local storage or URLs to structured Markdown format using Mistral AI's OCR API, preserving document structure and extracting images.
Updated a year ago (2025-06-27 22:25 UTC)
2
1
MIT
Mistral OCR MCP Server
Image & Video Processing AI & Machine Learning
lemopian
F
license
A
quality
D
maintenance
Extracts text content from PDFs and images using Mistral's OCR API, enabling OCR capabilities in MCP-compatible clients like Cursor and Claude Desktop.
Updated 5 months ago (2026-06-15 09:53 UTC)
1
8
-
DocMistral MCP Server
AI & Machine Learning Image & Video Processing Documentation Access
trsdn
A
license
Not graded
quality
B
maintenance
Converts documents and images to Markdown using Mistral AI's OCR, enabling AI-powered document processing via MCP-compatible clients like Claude Desktop.
Updated a day ago (2026-11-14 12:19 UTC)
77 npm
2
MIT

Mistral OCR MCP Server

Features

Client Configuration

Claude Desktop

OpenCode

Codex

Configuration

Required Environment Variables

Security Sandbox

Tool Reference

Tool 1: extract_markdown

Tool 2: extract_markdown_from_url

Tool 3: extract_markdown_advanced

Tool 4: ocr_status

Example Client Usage

Troubleshooting

Development

Setup

Run Tests

Project Structure

License

Contributing

Links

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-mistral-ocr

MCP-PDF2MD

Mistral OCR MCP Server

DocMistral MCP Server

Tool 1: `extract_markdown`

Tool 2: `extract_markdown_from_url`

Tool 3: `extract_markdown_advanced`

Tool 4: `ocr_status`