Skip to main content
Glama
ORDIS-Co-Ltd

Mistral OCR MCP Server

by ORDIS-Co-Ltd
OverviewSchemaRelated ServersScoreDiscussions
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: Lizeur

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

  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:

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.

Links

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ORDIS-Co-Ltd/mistral-ocr-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server