md_converter_mcp

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

| Approach | Input Tokens | Output Tokens | Total | Cost (Opus) | |----------|-------------|---------------|-------|-------------| | MCP tool call | ~100 | ~50 | ~150 | ~$0.003 | | LLM reads file + generates code | ~12,000 | ~2,000 | ~14,000 | ~$0.27 |

MCP is ~93x cheaper per conversion.

For a batch of 10 similar files:

| Approach | Total Tokens | Cost (Opus) | |----------|-------------|-------------| | MCP batch tool | ~500 | ~$0.01 | | LLM manual approach | ~100,000+ | ~$2.00+ |

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.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | input_path | string | required | Absolute path to .md file | | output_path | string | input + .pdf | Output file path | | theme | string | "default" | Theme name or path to .css | | page_size | string | "A4" | A4, Letter, A3, Legal | | margin_mm | int | 20 | Margins in mm (5-50) | | include_toc | bool | false | Generate table of contents | | header_text | string | null | Header with {title}, {date} placeholders | | footer_text | string | "{page} / {pages}" | Footer with page numbering |

md_converter_to_docx

Convert a single Markdown file to Word.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | input_path | string | required | Absolute path to .md file | | output_path | string | input + .docx | Output file path | | template | string | "default" | Template name or path to .docx | | include_toc | bool | false | Generate table of contents |

md_converter_batch

Convert multiple files at once.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | input_dir | string | required | Directory with .md files | | output_dir | string | input_dir | Output directory | | glob_pattern | string | "*/.md" | File matching pattern | | output_format | string | "pdf" | pdf, docx, or both | | theme | string | "default" | CSS theme (PDF) | | template | string | "default" | DOCX template | | page_size | string | "A4" | Paper size (PDF) | | margin_mm | int | 20 | Margins (PDF) | | include_toc | bool | false | Table of contents | | footer_text | string | "{page} / {pages}" | Footer (PDF) |

md_converter_list_themes

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

Themes

Built-in PDF themes

| Theme | Style | Best for | |-------|-------|----------| | default | Professional sans-serif (Inter), clean layout | Business docs, reports, notes | | academic | Serif fonts (Georgia), justified text, formal | Papers, articles, theses | | minimal | Light sans-serif, generous whitespace | Creative writing, simple docs |

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

| Component | Library | Why | |-----------|---------|-----| | MCP framework | FastMCP (Python SDK) | Best DX, @mcp.tool() decorator | | MD parser | markdown-it-py | Fast, CommonMark compliant | | Syntax highlighting | Pygments | 500+ languages | | PDF renderer | WeasyPrint | Full CSS3 print support, @page rules | | DOCX converter | pypandoc (pandoc) | Native DOCX writer, reference-doc templates | | Input validation | Pydantic v2 | Type-safe tool parameters |

License

MIT