Mistral Ocr Mcp — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Mistral Ocr Mcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
A Model Context Protocol (MCP) server that provides tools for extracting text and images from PDF and image files using the Mistral OCR API.
uvx without prior installation.pdf), PNG (.png), JPEG (.jpg, .jpeg), WebP (.webp), GIF (.gif)Add this to your claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%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"
}
}
}
}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"
}
}
}
}If you use the Codex CLI, you can add the server with:
codex mcp add mistral-ocr -- uvx mistral-ocr-mcpMake sure the environment variables MISTRAL_API_KEY and MISTRAL_OCR_ALLOWED_DIR are set in your shell environment.
| 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 |
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:
.. eliminated) before validationextract_markdownExtract 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):
report for report.pdf)report_20260102_143022<sanitized_id>.<ext> (e.g., img_abc123.png)content.md with relative image links (e.g., )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 imageextract_markdown_from_urlExtract 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"]
}extract_markdown_advancedExtract 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..."}ocr_statusCheck API connectivity and key validity.
Arguments: none
Returns:
{
"status": "ok",
"message": "API key is working"
}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())| 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 |
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_mcppytestmistral-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 fileMIT
Contributions are welcome! Please open an issue or submit a pull request.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.