md_converter_mcp

MCP server for converting Markdown files to print-ready PDF and Word (DOCX) with professional styling, page numbers, table of contents, and custom themes.

Built for local use with Claude Code — your Markdown files never leave your machine and never enter the LLM context window.

Why MCP instead of a script?

When you ask an LLM to convert a Markdown file, it has to:

1. Read the entire file into the context window
2. Write conversion code
3. Execute and debug it
4. Return the result

With an MCP server, the LLM just calls a tool with a file path. The heavy lifting happens outside the context window.

Token Usage Benchmark

Tested on a real 1,072-line Markdown file (37 KB, ~10,000 tokens):

MCP is ~93x cheaper per conversion.

For a batch of 10 similar files:

MCP is ~200x cheaper at batch scale because file contents never enter the context window.

Note: "LLM manual approach" estimates include reading files, writing/debugging conversion scripts, and processing output. Actual usage varies by model and conversation length.

Features

• PDF output via WeasyPrint with full CSS3 print support
• DOCX output via pandoc with reference document templates
• 3 built-in themes: default (professional sans-serif), academic (serif, formal), minimal (clean whitespace)
• Print-ready: page numbers, headers/footers, TOC generation, custom margins, page size selection
• Syntax highlighting: 500+ languages via Pygments
• Batch conversion: convert entire directories with glob patterns
• Custom themes: bring your own CSS or DOCX template

Installation

Prerequisites

# macOS
brew install pango pandoc

# Ubuntu/Debian
sudo apt install libpango-1.0-0 libpangocairo-1.0-0 pandoc

# Arch
sudo pacman -S pango pandoc

Install the server

git clone https://github.com/YOUR_USERNAME/md_converter_mcp.git
cd md_converter_mcp
uv sync --python 3.12

Generate the default DOCX template:

uv run python -m md_converter_mcp.create_default_template

Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "md_converter_mcp": {
      "command": "/absolute/path/to/md_converter_mcp/.venv/bin/python",
      "args": ["-m", "md_converter_mcp.server"]
    }
  }
}

Or with uv:

{
  "mcpServers": {
    "md_converter_mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/md_converter_mcp", "md-converter-mcp"]
    }
  }
}

Usage

In Claude Code (natural language)

Convert /path/to/notes.md to PDF with the academic theme

Batch convert all markdown files in /path/to/docs/ to both PDF and DOCX with TOC

Make a PDF from my-file.md with A4 pages, 25mm margins, and page numbers

Available Tools

#### md_converter_to_pdf

Convert a single Markdown file to PDF.

#### md_converter_to_docx

Convert a single Markdown file to Word.

#### md_converter_batch

Convert multiple files at once.

#### md_converter_list_themes

List all available CSS themes and DOCX templates. No parameters.

Themes

Built-in PDF themes

Custom themes

Create a CSS file with @page rules and body styling:

@page {
    size: {{ page_size }};
    margin: {{ margin_mm }}mm;
    @bottom-center {
        content: {{ footer_content }};
    }
}
body {
    font-family: "Your Font", sans-serif;
    font-size: 11pt;
}

Use it by passing the absolute path:

Convert my-file.md to PDF with theme /path/to/my-theme.css

Or place it in ~/.config/md_converter_mcp/themes/mytheme.css and reference by name:

Convert my-file.md to PDF with theme mytheme

Architecture

Markdown file
    |
    +---> [markdown-it-py] ---> HTML ---> [WeasyPrint + CSS theme] ---> PDF
    |
    +---> [pandoc + reference-doc template] ---> DOCX

• PDF path: markdown-it-py parses MD to HTML, Pygments highlights code blocks, WeasyPrint renders with CSS @page rules for print layout
• DOCX path: pandoc handles everything natively — better DOCX structure than any HTML-to-DOCX approach
• Async: synchronous rendering (WeasyPrint, pandoc) runs in asyncio executor to avoid blocking the MCP event loop

Project Structure

md_converter_mcp/
├── pyproject.toml
├── uv.lock
├── src/
│   └── md_converter_mcp/
│       ├── server.py                # FastMCP entry point, 4 tools
│       ├── models.py                # Pydantic v2 input models
│       ├── create_default_template.py
│       ├── converter/
│       │   ├── markdown_parser.py   # MD -> HTML + Pygments + TOC
│       │   ├── pdf_renderer.py      # HTML -> PDF (WeasyPrint)
│       │   ├── docx_renderer.py     # MD -> DOCX (pypandoc)
│       │   └── pipeline.py          # Single + batch orchestration
│       └── styling/
│           ├── theme_manager.py     # Theme/template resolution
│           └── themes/
│               ├── default.css
│               ├── academic.css
│               ├── minimal.css
│               └── default_ref.docx
└── tests/
    └── fixtures/
        └── sample.md

Tech Stack

License

MIT