<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](https://modelcontextprotocol.io) server that wraps [mdify](https://github.com/jupinsker/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

```bash
pip install mdify-mcp
```

### Requirements

- Python 3.10+
- [Ollama](https://ollama.com) 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`:

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

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

### VS Code

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

```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

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

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector mdify-mcp
```

## License

[Apache License 2.0](LICENSE) — see [LICENSE](LICENSE) for details.