Skip to main content
Glama
sham-devs

mcp-md-pdf

by sham-devs
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

PyPI version Python Versions Tests License: MIT

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.

Related MCP server: AI Group Markdown to Word MCP Server

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:

Method

Code Download?

PDF Support

Best For

uvx (Option 1)

❌ No

✅ Yes (LibreOffice required)

Claude Desktop users

pip (Option 2)

❌ No

✅ Yes (LibreOffice required)

Python package users

From Source (Option 3)

✅ Yes

✅ Yes (LibreOffice required)

Developers

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

Feature

Supported

Notes

Headings (H1–H6)

✅

# through ######, with template fallback

Bold / Italic

✅

Markdown standard syntax

Inline code

✅

Monospaced with gray background

Code blocks

✅

Professional styling with background and borders

Bullet & Numbered lists

✅

Nested up to 3 levels

Tables

✅

With header styling and inline formatting

Blockquotes

✅

Italic text with left border and background shading

Horizontal rules

✅

---

Unicode & Emoji

✅

Full UTF-8 support

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:

    • Windows: %APPDATA%\Claude\logs\

    • macOS: ~/Library/Logs/Claude/

  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.

Available Tools

3 tools
convert_markdownB

Convert markdown to Word/PDF with optional .dotx template.

This tool converts markdown files to professional documents using python-docx. You can optionally provide a .dotx template file for consistent styling.

ParametersJSON Schema
NameRequiredDescriptionDefault
output_pathYesBase path for output (without extension)
markdown_pathYesPath to input .md file
output_formatNoOutput format - "docx" (Word), "pdf", or "both"docx
template_pathNoOptional path to .dotx template file for styling

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It mentions using python-docx and optional template styling, but fails to explain overwriting behavior, output return values, failure modes, or dependencies for PDF conversion. This is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, with the core purpose in the first line. However, the second paragraph partially restates the first sentence ('This tool converts markdown files to professional documents'), introducing minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a conversion tool with four parameters and no annotations, the description provides a basic overview but omits important context such as output file naming (e.g., extension handling), error cases, and PDF conversion details. An output schema may exist, but the description alone is not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters with 100% description coverage, so the baseline is 3. The description adds minimal extra meaning beyond the schema, such as hinting at output format and template purpose, but does not significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Convert markdown to Word/PDF' which is a specific verb and resource. It also mentions the optional .dotx template, distinguishing this tool from the batch variant and list_supported_formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies single-file conversion but does not explicitly state when to use this tool versus convert_markdown_batch. There is no mention of exclusions or alternatives, leaving usage guidance to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_markdown_batchA

Batch convert multiple markdown files to Word/PDF.

Converts a list of markdown files using the same template and format settings. Output files are named after input files and placed in the specified directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
output_dirYesDirectory for output files
output_formatNoOutput format for all files - "docx", "pdf", or "both"docx
template_pathNoOptional shared template for all conversions
markdown_filesYesList of paths to .md files

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry full behavioral burden. It explains output naming ('Output files are named after input files and placed in the specified directory') and shared settings, but it does not address potential side effects like overwriting existing files, error handling, or whether input files are modified. This adds some context but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the core purpose. Every sentence adds meaningful information—batch conversion, shared settings, and output naming—with no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main batch behavior, output naming, and shared settings, which is sufficient for a 4-parameter tool with full schema coverage and an output schema. It could be improved by mentioning whether files are processed sequentially and how errors are handled, but the core is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters have descriptions. The tool description mentions 'same template and format settings' which loosely ties to template_path and output_format, but it does not add significant detail beyond what the schema already provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Batch convert multiple markdown files to Word/PDF.' It specifies the action, resource, and scope, and the 'batch' / 'multiple' phrasing distinguishes it from the sibling tool convert_markdown for single files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than explicitly stated. The description says 'Batch convert multiple markdown files' and mentions shared template/format settings, which suggests when to use it, but it does not explicitly say 'use this instead of convert_markdown for multiple files' or define when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_supported_formatsA

List all supported input/output formats and features.

Returns: Information about supported formats and features

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries some burden. It explicitly states that the tool returns information about formats and features, implying a read-only query behavior. However, it does not describe the structure of the return data or any potential limitations (e.g., whether the list is exhaustive or dependent on the environment). The stated behavior is simple but adequate for a format-listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core purpose. The second sentence ('Returns: Information about supported formats and features') is largely redundant with the first sentence, which slightly reduces its efficiency, but overall it remains appropriately concise for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no nested objects) and the presence of an output schema, the description provides sufficient context. It states the tool lists formats and features and returns information about them. It does not explain when to use it, but for a discovery tool with an output schema, this is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the input schema is empty, so there is no parameter semantics to cover. The description correctly does not attempt to document nonexistent parameters, and the baseline for zero-parameter tools is 4 since no compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('all supported input/output formats and features'). It clearly distinguishes itself from the sibling conversion tools by identifying itself as a capabilities/discovery tool rather than a conversion operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when one needs to know which formats and features are supported, but it provides no explicit guidance on when to use this tool versus the sibling conversion tools. The 'List all' phrasing gives some context, but no exclusions or alternative recommendations are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedconvert_markdown
    • First observedconvert_markdown_batch
    • First observedlist_supported_formats
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

The three tools have clearly distinct purposes: single-file conversion, batch conversion, and format listing. No overlap or ambiguity exists between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: convert_markdown, convert_markdown_batch, list_supported_formats. The batch suffix and list verb are logical extensions.

Tool Count5/5

Three tools is well-scoped for a focused Markdown-to-Word/PDF converter. Each tool serves a distinct, necessary function without bloat or redundancy.

Completeness5/5

The tool surface fully covers the conversion workflow: single conversion, batch conversion, and discovering supported formats. No obvious gaps exist for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sham-devs/mcp-md-pdf'

If you have feedback or need assistance with the MCP directory API, please join our Discord server