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:
output_dir parameter must be within MISTRAL_OCR_ALLOWED_DIRValidation 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 content from a document without saving images.
Arguments:
{
"file_path": "/absolute/path/to/document.pdf"
}| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Absolute path to input file (PDF or image) |
Returns:
"# Document Title\n\nExtracted markdown content from all pages..."Returns a single string containing concatenated markdown from all pages.
Example:
{
"tool": "extract_markdown",
"arguments": {
"file_path": "/Users/username/documents/report.pdf"
}
}extract_markdown_with_imagesExtract markdown content and save embedded images to disk.
Arguments:
{
"file_path": "/absolute/path/to/document.pdf",
"output_dir": "/absolute/path/to/output/parent"
}| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Absolute path to input file (PDF or image) |
output_dir | string | Yes | Absolute path to output parent directory (must exist and be writable, must be within MISTRAL_OCR_ALLOWED_DIR) |
Returns:
{
"output_directory": "/absolute/path/to/output/parent/document",
"markdown_file": "/absolute/path/to/output/parent/document/content.md",
"images": ["img_abc123.png", "img_def456.jpeg"]
}| Field | Type | Description |
|---|---|---|
output_directory | string | Absolute path to created subdirectory |
markdown_file | string | Absolute path to content.md file |
images | array[string] | List of saved image filenames (not full paths) |
Behavior:
report for report.pdf)report_20260102_143022<sanitized_id>.<ext> (e.g., img_abc123.png)content.md with relative image links (e.g., )Example:
{
"tool": "extract_markdown_with_images",
"arguments": {
"file_path": "/Users/username/documents/quarterly-report.pdf",
"output_dir": "/Users/username/workdir/extracted"
}
}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 imageHere'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()
# Simple 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_with_images",
arguments={
"file_path": "/path/to/document.pdf",
"output_dir": "/Users/username/workdir/output"
}
)
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.