mdify-mcp

<p align="center"> <h1 align="center">mdify-mcp</h1> <p align="center"> MCP server that gives LLMs the power to convert PDFs to Markdown on the fly </p> </p>

<p align="center"> <a href="https://pypi.org/project/mdify-mcp/"><img src="https://img.shields.io/pypi/v/mdify-mcp?color=blue" alt="PyPI"></a> <a href="https://pypi.org/project/mdify-mcp/"><img src="https://img.shields.io/pypi/pyversions/mdify-mcp" alt="Python"></a> <a href="https://github.com/jupinsker/mdify-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/jupinsker/mdify-mcp" alt="License"></a> <a href="https://github.com/jupinsker/mdify-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/jupinsker/mdify-mcp/ci.yml?label=CI" alt="CI"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP"></a> </p>

---

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

Available Tools

| Tool | Description | |------|-------------| | convert | Convert a single PDF file to Markdown | | batch_convert | Convert all PDFs in a directory | | read_markdown | Read the contents of a converted Markdown file | | check_ollama | Check if Ollama is installed and the model is available | | pull_ollama_model | Download an Ollama model | | list_pdfs | List all PDF files in a directory | | list_markdowns | List all Markdown files in a directory |

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

| Variable | Default | Description | |----------|---------|-------------| | MDIFY_MODEL | qwen2.5vl:3b | Ollama model tag | | MDIFY_DPI | 200 | PDF render resolution | | MDIFY_OLLAMA_URL | http://localhost:11434/v1/chat/completions | Ollama API endpoint |

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.