MCP-MD-PDF: Markdown to Word/PDF Converter

A simple, reliable Model Context Protocol (MCP) server that converts Markdown files into professional Word (.docx) and PDF documents — with full support for `.dotx` templates.

Background

This tool was born from a practical need.

We often write documentation, guides, and technical notes in Markdown — it’s fast, lightweight, and easy to version.

But when it’s time to deliver these files to clients or present them professionally, we usually want them to match our project or company style: clean layout, consistent fonts, branded cover page, and polished formatting.

So instead of doing that manually every time, we built a simple flow:

> Convert Markdown → Word (.docx using a `.dotx` template) → PDF

By using Word templates, we could apply our own design once and keep every document consistent.

That’s where this small project came from — a quick way to turn Markdown into beautiful, ready-to-share documents that look like they belong to your organization.

Features

• 🚀 Fast Conversion – From Markdown to Word or PDF in seconds
• 🎨 Template Support – Apply `.dotx` templates for consistent, branded styling
• 📦 Batch Processing – Convert multiple files at once
• 🔧 Flexible Output – Choose between `.docx`, `.pdf`, or both
• 🤖 AI-Ready – Built to integrate smoothly with Claude and other MCP-compatible AI tools

Installation

Choose the installation method that best fits your needs:

Option 1: Using `uvx` (Recommended - No Code Download Needed)

Best for: Claude Desktop users who want the simplest installation.

Requirements:

• Python 3.10+
• For PDF conversion:
  • Windows: Microsoft Word (uses COM automation)
  • macOS: LibreOffice (`brew install --cask libreoffice`)
  • Linux: LibreOffice (`sudo apt-get install libreoffice`)

Installation:

# No code download needed - uvx handles everything
uvx mcp-md-pdf

Claude Desktop Setup:

Add to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "md-pdf": {
      "command": "uvx",
      "args": ["mcp-md-pdf"]
    }
  }
}

Restart Claude Desktop for changes to take effect.

> 📖 See Configuration section for config file location and alternative setups.

Option 2: Using `pip` (No Code Download Needed)

Best for: Users who want to install as a Python package.

Requirements:

• Python 3.10+
• For PDF conversion (same as Option 1):
  • Windows: Microsoft Word
  • macOS/Linux: LibreOffice

Installation:

# Install from PyPI (when published)
pip install mcp-md-pdf

# Or install with development dependencies
pip install "mcp-md-pdf[dev]"

Claude Desktop Setup:

Add to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

Restart Claude Desktop for changes to take effect.

> 📖 See Configuration section for config file location and alternative setups.

Option 3: From Source (Code Download Required)

Best for: Developers who want to modify the code or contribute.

Requirements:

• Git
• Python 3.10+
• For PDF conversion (same as above)

Installation:

# Step 1: Clone the repository
git clone https://github.com/sham-devs/mcp-md-pdf.git
cd mcp-md-pdf

# Step 2: Install in development mode
pip install -e .

# Step 3: (Optional) Install dev dependencies
pip install -e ".[dev]"

Claude Desktop Setup:

Add to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

Restart Claude Desktop for changes to take effect.

> 📖 See Configuration section for config file location and alternative setups.

Configuration

Step 1: Find Your Configuration File

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Step 2: Add MCP Server

Open the configuration file and add the mcp-md-pdf server:

Option A: Using uvx (Recommended)

{
  "mcpServers": {
    "md-pdf": {
      "command": "uvx",
      "args": ["mcp-md-pdf"]
    }
  }
}

Option B: Local Installation

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

Option C: With Environment Variables

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-md-pdf"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop for changes to take effect.

Usage

With Claude Desktop

After setup, restart Claude Desktop and simply ask:

Convert my README.md to Word format

Convert docs.md to PDF using my company-template.dotx

Convert all markdown files in the docs folder to both Word and PDF

MCP Tools

1. `convert_markdown`

Convert a single Markdown file to Word or PDF.

Parameters:

• `markdown_path` *(str)* – Path to the `.md` file
• `output_path` *(str)* – Output base path (no extension)
• `output_format` *(str)* – `"docx"`, `"pdf"`, or `"both"` (default: `"docx"`)
• `template_path` *(str, optional)* – Path to `.dotx` template

Examples:

# Create Word document
convert_markdown("README.md", "output", "docx")

# Create PDF with template
convert_markdown("doc.md", "result", "pdf", "template.dotx")

# Create both formats
convert_markdown("guide.md", "final", "both", "company.dotx")

2. `convert_markdown_batch`

Convert multiple Markdown files at once.

Parameters:

• `markdown_files` *(list[str])* – List of `.md` files
• `output_dir` *(str)* – Output directory
• `output_format` *(str)* – `"docx"`, `"pdf"`, or `"both"`
• `template_path` *(str, optional)* – Shared `.dotx` template

Example:

convert_markdown_batch(
  ["doc1.md", "doc2.md", "doc3.md"],
  "output",
  "both",
  "template.dotx"
)

3. `list_supported_formats`

List supported formats and their capabilities.

Supported Markdown Features

**For detailed feature coverage analysis, see docs/MARKDOWN_COVERAGE.md**

Template Support

Use a `.dotx` Word template to define your document style:

• Custom headings, fonts, and colors
• Page margins and layout
• Headers and footers
• Branding and logo placement
• Table of contents formatting

If no template is provided, a clean default design is used.

PDF Conversion Setup

Important: PDF conversion requires LibreOffice (or Microsoft Word on Windows) to preserve all DOCX formatting.

Why LibreOffice?

LibreOffice is required for PDF conversion because it preserves ALL formatting from DOCX files:

• ✅ Colors, backgrounds, borders - Professional styling intact
• ✅ Code blocks - Syntax highlighting and backgrounds preserved
• ✅ Tables - Headers, borders, and cell styling maintained
• ✅ Template styles - `.dotx` template formatting carried through to PDF
• ✅ Fonts & spacing - Typography remains pixel-perfect

Alternative approaches (Pandoc, etc.) lose formatting - they treat DOCX as plain text markup, stripping visual styles during PDF conversion.

DOCX Conversion (All Platforms)

✅ Works out of the box - no additional software needed!

PDF Conversion (Platform-Specific)

Windows Users

Option A: Microsoft Word (Best for Windows)

If you have Microsoft Word installed:

# Install Python COM automation library
pip install pywin32

That's it! The converter will automatically use Word for PDF conversion.

Option B: LibreOffice (Recommended if no Word)

# Method 1: Direct download (easiest)
# Visit: https://www.libreoffice.org/download/

# Method 2: Using Chocolatey package manager
choco install libreoffice

# Method 3: Using winget (Windows Package Manager)
winget install TheDocumentFoundation.LibreOffice

Verify installation:

# Check if LibreOffice is installed
where.exe soffice
# Should output: C:\Program Files\LibreOffice\program\soffice.exe

macOS Users

LibreOffice is REQUIRED for PDF conversion on macOS (no native MS Word COM support).

Installation (Choose one method):

# Method 1: Homebrew (RECOMMENDED - easiest updates)
brew install --cask libreoffice

# Method 2: Direct download
# Visit: https://www.libreoffice.org/download/
# Download LibreOffice_25.x.x_MacOS_aarch64.dmg (M1/M2/M3)
# Or LibreOffice_25.x.x_MacOS_x86-64.dmg (Intel Macs)

System Requirements:

• macOS 10.15 (Catalina) or newer
• ~800 MB disk space
• Works on both Intel and Apple Silicon (M1/M2/M3)

Verify installation:

which soffice
# Should output: /Applications/LibreOffice.app/Contents/MacOS/soffice

libreoffice --version
# Should output: LibreOffice 25.x.x or higher

Linux Users

Ubuntu/Debian (Recommended method):

# Update package list
sudo apt-get update

# Install LibreOffice (headless mode supported)
sudo apt-get install -y libreoffice libreoffice-writer

# Optional: Install additional fonts for better compatibility
sudo apt-get install -y fonts-liberation fonts-dejavu

For headless servers (CI/CD):

# Minimal installation without GUI components
sudo apt-get install -y libreoffice-writer libreoffice-calc \
  libxinerama1 libfontconfig1 libdbus-glib-1-2 libcairo2 \
  libcups2 libglu1-mesa libsm6

Fedora/RHEL:

sudo dnf install libreoffice libreoffice-writer

Arch Linux:

sudo pacman -S libreoffice-fresh

Verify installation:

libreoffice --version
# Should output: LibreOffice 7.x or 25.x

# Test headless mode
soffice --headless --version
# Should output version without GUI

Platform Notes

• DOCX Conversion: Works on all platforms (Windows, macOS, Linux) - no additional software required
• PDF Conversion: Cross-platform with automatic platform detection:
  • Windows: Uses Microsoft Word (if installed) or LibreOffice
  • macOS/Linux: Uses LibreOffice in headless mode

Why LibreOffice for PDF? LibreOffice preserves ALL DOCX formatting when converting to PDF:

• ✅ Colors, backgrounds, and borders
• ✅ Professional code block styling (#F5F5F5 backgrounds)
• ✅ Blockquote borders (blue left border)
• ✅ Table headers with colored backgrounds
• ✅ Template styles from .dotx files
• ✅ Fonts, spacing, and layout

Requirements

• Python 3.10+
• `Pillow` (image handling)
• `python-docx` (Word generation)
• `pywin32` (Windows only)
• `fastmcp` (MCP framework)

Development

# Clone the repository
git clone https://github.com/sham-devs/mcp-md-pdf.git
cd mcp-md-pdf

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/md_pdf_mcp --cov-report=html

# Format code
black src/ tests/
ruff check src/ tests/

Testing

Covers:

• Markdown → Word conversion
• Template application
• MCP server tools
• Unicode, emoji, and edge cases

Structure:

tests/
├── conftest.py
├── test_converter.py
├── test_server.py
└── README.md

Examples

# Run the MCP server directly
python -m md_pdf_mcp.server

Or inspect via:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

Example usage:

User: Convert my README.md to Word format
→ Created: README.docx

User: Create a PDF with our company template
→ Created: guide.pdf

User: Convert all docs to both formats
→ Batch Conversion Complete (5 succeeded, 0 failed)

Troubleshooting

Server Not Showing Up in Claude Desktop

1. Verify `claude_desktop_config.json` is valid JSON (no trailing commas)

2. Check that the Python path is correct for your system

3. Review Claude Desktop logs:

4. Restart Claude Desktop completely

Python Path Issues

Verify your Python installation:

python --version
# or
python3 --version

If the command doesn't work, find your Python path:

• Windows: `where python`
• macOS/Linux: `which python3`

Update the configuration file with the correct path.

PDF Conversion Fails

Error: `pywin32 library required for PDF conversion on Windows`

Fix (Windows):

pip install pywin32

Error: `LibreOffice not found`

Fix (macOS):

brew install --cask libreoffice

Fix (Ubuntu/Debian):

sudo apt-get install libreoffice libreoffice-writer

Fix (Fedora):

sudo dnf install libreoffice

Template Not Loading

Error: Invalid or missing `.dotx` file

Fix:

• Verify the file path and extension are correct
• Ensure the template file exists and is accessible
• Try conversion without template to isolate the issue

Import Errors

Error: `ModuleNotFoundError: No module named 'fastmcp'`

Fix:

• Run `pip install -e .` from the project directory
• Or install from PyPI: `pip install mcp-md-pdf`

Testing with MCP Inspector

For advanced debugging, test the server directly:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

This opens a web interface to interact with the MCP tools directly.

License

MIT License – see `LICENSE` file.

Contributing

Pull requests are welcome.

If you have ideas for improving conversions, templates, or new formats, we’d love to see them.

Credits

Built with ❤️ using the FastMCP framework —

created to make Markdown documents look like real reports, not just text on GitHub.