Mistral OCR MCP Server
A Model Context Protocol (MCP) server that converts PDF documents to Markdown using Mistral's OCR API.
Features
- Convert PDF files to Markdown format using Mistral OCR
- Support for both local PDF files and URLs
- Automatic file upload and processing for local PDFs
- Configurable output directory via environment variables
- Image extraction: Extract and save images from PDFs with automatic path correction
- Multi-page document support with page markers
- Preserves document structure, tables, and formatting
Prerequisites
- Python 3.10 or higher
- UV package manager
- Mistral API key (Get one here)
Installation
1. Install UV (if not already installed)```bash
On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
### 2. Clone and setup the project```bash
cd mistral-ocr-mcp
# Copy the example environment file
cp .env.example .env
# Edit .env and add your Mistral API key
# MISTRAL_API_KEY=your_api_key_here
3. Install dependencies with UV```bash
uv sync
## Configuration
Create a `.env` file in the project root with the following variables:```bash
# Required: Your Mistral API key
MISTRAL_API_KEY=your_api_key_here
# Optional: Output directory for converted files (defaults to ./output)
MISTRAL_OUTPUT_DIR=./output
Usage
Running with UV```bash
Run directly with uvx (no installation needed)
uvx --from . mistral-ocr-mcp
Or with uv run
uv run mistral-ocr-mcp
### Running in development mode```bash
uv run python -m mistral_ocr_mcp.server
MCP Client Configuration
To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:
For Claude Desktop
Add to your claude_desktop_config.json:```json
{
"mcpServers": {
"mistral-ocr": {
"command": "uvx",
"args": [
"--from",
"C:\Projects\GitHub\mistral-ocr-mcp",
"mistral-ocr-mcp"
],
"env": {
"MISTRAL_API_KEY": "your_api_key_here",
"MISTRAL_OUTPUT_DIR": "C:\path\to\output"
}
}
}
}
Or use the local path with `uv`:```json
{
"mcpServers": {
"mistral-ocr": {
"command": "uv",
"args": [
"--directory",
"C:\\Projects\\GitHub\\mistral-ocr-mcp",
"run",
"mistral-ocr-mcp"
],
"env": {
"MISTRAL_API_KEY": "your_api_key_here",
"MISTRAL_OUTPUT_DIR": "C:\\path\\to\\output"
}
}
}
}
Available Tools
convert_pdf_to_markdown
Converts a PDF document to Markdown format.
Parameters:
- source (required): Path to local PDF file or URL to PDF document
- output_filename (optional): Custom output filename without extension
- include_images (optional): Whether to include base64-encoded images (default: false)
Example without images:```json
{
"source": "C:\documents\report.pdf",
"output_filename": "my_report",
"include_images": false
}
**Example with image extraction:**```json
{
"source": "https://arxiv.org/pdf/2501.00663",
"output_filename": "research_paper",
"include_images": true
}
get_output_directory
Returns the current output directory path.
Features in Detail
Local PDF Processing
The server handles local PDFs by:
1. Uploading the file to Mistral's secure storage
2. Generating a signed URL
3. Processing the document with OCR
4. Saving the markdown output locally
URL-based Processing
PDFs accessible via URL are processed directly without upload:```json
{
"source": "https://arxiv.org/pdf/2501.00663"
}
### Multi-page Documents
Each page is processed and marked with a comment in the output:```markdown
[Content from page 1]
[Content from page 2]
Image Extraction
When include_images is set to true, the server will:
- Create a document folder with the PDF's original name
- Extract all images from the PDF document
- Save images to an
images/subdirectory within the document folder - Update markdown references to use the simple path
images/img-X.jpeg - Preserve image IDs from Mistral OCR (e.g.,
img-0.jpeg,img-1.jpeg) - Save the markdown file in the document folder alongside the images
Directory structure after conversion with images:```
output/
└── research_paper/
├── research_paper.md
└── images/
├── img-0.jpeg
├── img-1.jpeg
└── img-2.jpeg
Each PDF conversion creates its own folder containing:
- The markdown file (same name as PDF + `.md`)
- An `images` subfolder with all extracted images
**Markdown output with images:**```markdown
# Document Title
Here is a chart showing the results:

The data shows...
Image references use the simple relative path images/img-X.jpeg, which works reliably in all markdown viewers.
Image format:
- Images are extracted from base64-encoded data URIs in the OCR response
- The base64 data is decoded and saved as binary image files
- Saved in their original format (typically JPEG or PNG)
- Markdown references are automatically updated to use relative paths
- Can be viewed directly in markdown viewers that support relative paths
How it works:
1. Creates a folder with the PDF's original name in the output directory
2. Mistral OCR returns images as base64-encoded data URIs (e.g., data:image/jpeg;base64,/9j/4AAQ...)
3. The server extracts the base64 portion, decodes it to binary data
4. Saves each image with its ID as the filename (e.g., img-0.jpeg) in the images/ subfolder
5. Updates markdown to reference images using the simple relative path images/img-X.jpeg
6. Saves the markdown file in the same folder as the images
Note: Image extraction increases processing time and API response size. Only enable when you need to preserve visual elements like charts, diagrams, photos, or illustrations from the PDF.
Limitations
- PDF files must be under 50 MB
- Maximum 1000 pages per request
- Supported file format: PDF only
Pricing
Mistral OCR costs $1 per 1000 pages ($0.001 per page). Check Mistral's pricing page for current rates.
Troubleshooting
"MISTRAL_API_KEY environment variable is required"
Make sure you've created a .env file with your API key or set the environment variable in your MCP client configuration.
"File not found" error
Ensure the PDF file path is absolute and the file exists. On Windows, use double backslashes or forward slashes in paths.
Permission errors
Make sure the output directory exists and is writable. The server will attempt to create it if it doesn't exist.
VS Code not showing images in markdown preview
If images aren't displaying in VS Code's markdown preview:
-
Check file structure: The new folder structure keeps everything organized:
output/ └── document_name/ ├── document_name.md └── images/ ├── img-0.jpeg └── img-1.jpeg -
Verify image paths: Open the markdown file and check the image references:
- Should be:` - Uses simpleimages/path (not complex folder names with spaces) - Uses forward slashes/(not backslashes`)
- Path is relative to the markdown file -
Open the document folder: Navigate into the document folder (e.g.,
output/document_name/) and open the markdown file from there. VS Code resolves relative paths from the markdown file's location. -
Check actual image files exist: Navigate to the
images/subfolder and verify the.jpegfiles are there and can be opened. -
Restart VS Code: Sometimes VS Code's markdown preview cache needs refreshing. Close and reopen VS Code or run "Developer: Reload Window" from the command palette.
The simplified folder structure with images/ avoids issues with spaces and special characters in paths.
Development
Project structure```
mistral-ocr-mcp/
├── mistral_ocr_mcp/
│ ├── init.py
│ └── server.py # Main MCP server implementation
├── pyproject.toml # UV project configuration
├── .env.example # Example environment variables
├── .gitignore
└── README.md
### Running tests```bash
# Install dev dependencies
uv sync --dev
# Run tests (when added)
uv run pytest
License
MIT
References
- Mistral OCR Documentation
- Model Context Protocol
- UV Package Manager
