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)

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

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:

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:

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):

1. Creates a subdirectory named after the input file stem (e.g., report for report.pdf)
2. If the subdirectory already exists, appends a timestamp: report_20260102_143022
3. Saves all extracted images as <sanitized_id>.<ext> (e.g., img_abc123.png)
4. 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:

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:

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

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.

Links

• GitHub Repository: https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
• MCP Specification: https://modelcontextprotocol.io
• Mistral AI: https://mistral.ai