mdify-mcp

mdify-mcp is a Model Context Protocol server that wraps mdify — enabling any MCP-compatible client (Claude Desktop, Cursor, VS Code Copilot, etc.) to convert PDF documents to Markdown using a local Ollama vision model.

No cloud APIs. No data leaves your machine. Just point an LLM at a PDF and get structured Markdown back.

Features

• 7 tools for complete PDF→Markdown workflow

• Fully local — powered by Ollama + Qwen2.5-VL running on your machine

• Zero config — works out of the box with sensible defaults

• Batch processing — convert entire directories of PDFs

• Ollama management — check status and pull models directly from chat

• Standard MCP — works with any MCP-compatible client

Related MCP server: flint-slating

Available Tools

Installation

pip install mdify-mcp

Requirements

• Python 3.10+

• Ollama installed and running locally

• A pulled Qwen2.5-VL model (the server can pull it for you via the pull_ollama_model tool)

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mdify": {
      "command": "mdify-mcp",
      "env": {
        "MDIFY_MODEL": "qwen2.5vl:3b",
        "MDIFY_OLLAMA_URL": "http://localhost:11434/v1/chat/completions"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "mdify": {
      "command": "mdify-mcp"
    }
  }
}

VS Code

Add to your VS Code settings (.vscode/mcp.json):

{
  "servers": {
    "mdify": {
      "command": "mdify-mcp",
      "env": {
        "MDIFY_MODEL": "qwen2.5vl:3b"
      }
    }
  }
}

Environment Variables

Usage Examples

Once configured, you can ask your LLM things like:

"Convert the PDF at /home/user/docs/report.pdf to Markdown"

"Convert all PDFs in /home/user/papers/ and save the Markdown files to /home/user/markdown/"

"Check if Ollama is set up correctly for PDF conversion"

"Pull the qwen2.5vl:7b model for better accuracy"

"List all PDFs in my documents folder"

"Read the Markdown file that was just converted"

How it works

┌──────────────┐     MCP (stdio)     ┌──────────────┐     HTTP      ┌──────────┐
│  LLM Client  │ ◄─────────────────► │  mdify-mcp   │ ────────────► │  Ollama  │
│  (Claude,    │     tool calls      │  (FastMCP)   │  image+prompt │  (local) │
│   Cursor…)   │                     │              │               │          │
└──────────────┘                     └──────┬───────┘               └──────────┘
                                            │
                                     ┌──────┴───────┐
                                     │    mdify     │
                                     │  (converter) │
                                     └──────────────┘

1. LLM client sends a tool call via MCP (stdio transport)

2. mdify-mcp validates parameters and calls the mdify converter

3. mdify renders PDF pages → images → sends to Ollama for VLM inference

4. Structured Markdown is written to disk and the result is returned to the LLM

Development

git clone https://github.com/jupinsker/mdify-mcp.git
cd mdify-mcp
pip install -e ".[dev]"
pytest

Testing with MCP Inspector

npx @modelcontextprotocol/inspector mdify-mcp

License

Apache License 2.0 — see LICENSE for details.