Creating Custom MCP Servers (with Mistral OCR Example)

Overview

This guide explains how to create custom Model Context Protocol (MCP) servers, focusing on a Python implementation style inspired by the "Claude Reads LinkedIn Profiles" YouTube tutorial. It also includes a real-world example: a custom MCP server that wraps the Mistral OCR API.

1. What is an MCP Server?

An MCP server exposes tools and resources to extend AI assistants like Claude, Cursor, or WindSurf. It acts as a bridge to APIs, databases, or custom logic.

2. Prerequisites

• Python 3.8+
• uv package manager (recommended, replaces pip/venv)
• mcp-cli Python SDK
• httpx for async HTTP requests
• Mistral API key

3. Setup Environment

# Create project directory
mkdir mistral-ocr-mcp-server
cd mistral-ocr-mcp-server

# Initialize virtual environment
uv venv

# Activate environment
source .venv/bin/activate  # macOS/Linux
# .\.venv\Scripts\activate  # Windows

# Install dependencies
uv pip install mcp-cli httpx python-dotenv mistralai

4. MCP Server Implementation (Python)

4.1. Environment Variables

Create a .env file:

MISTRAL_API_KEY=LybX5GSEXVmDEeQjlEZyTUog5tUmmqcO

4.2. Server Code (server.py)

import os
import asyncio
from dotenv import load_dotenv
import httpx
from mistralai import Mistral
from mcp import fast_mcp, tool, run, Stdio

load_dotenv()
api_key = os.environ["MISTRAL_API_KEY"]
client = Mistral(api_key=api_key)

mcp_server = fast_mcp(
    name="mistral-ocr-server",
    description="MCP server for Mistral OCR API"
)

@tool(
    name="extract_ocr_from_file",
    description="Upload a PDF/image, perform OCR, and return extracted text",
    input_schema={
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "Local path to the PDF or image file"
            }
        },
        "required": ["file_path"]
    }
)
async def extract_ocr_from_file(file_path: str):
    # Upload file
    with open(file_path, "rb") as f:
        uploaded_pdf = client.files.upload(
            file={
                "file_name": os.path.basename(file_path),
                "content": f
            },
            purpose="ocr"
        )
    # Get signed URL
    signed_url = client.files.get_signed_url(file_id=uploaded_pdf.id)
    # Perform OCR
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": signed_url.url
        },
        include_image_base64=False
    )
    return ocr_response

if __name__ == "__main__":
    asyncio.run(run(mcp_server, transport=Stdio()))

5. Configure MCP Client

Edit your MCP settings file:

/Users/macbook202201/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add:

{
  "mcpServers": {
    "mistral-ocr-server": {
      "command": "/path/to/uv",  // Use `which uv` to get path
      "args": [
        "run",
        "/Users/macbook202201/Documents/Cline/MCP/mistral-ocr-mcp-server/server.py"
      ],
      "env": {
        "MISTRAL_API_KEY": "LybX5GSEXVmDEeQjlEZyTUog5tUmmqcO"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

6. Usage

Once configured and running, the MCP server exposes a tool:

extract_ocr_from_file

• Input: { "file_path": "/path/to/your/document.pdf" }
• Output: OCR result JSON from Mistral API.

7. Notes

• You can extend this server with more tools (e.g., chat with document, batch OCR).
• The same approach applies to other APIs.
• Inspired by the YouTube tutorial's Python style: uv, mcp-cli, decorators, async HTTP.

8. References

• Mistral API Docs
• Model Context Protocol SDK
• YouTube Tutorial