Markdown2doc MCP Server for Pandoc File Conversion

Overview

The Markdown2doc MCP Server is an MCP (Model Context Protocol) server that wraps Pandoc to convert documents between common formats (Markdown, DOCX, HTML, PDF, EPUB, LaTeX, etc.). It is intended for use inside the Klavis/MCP ecosystem where language models or orchestration layers need reliable, server-side file format conversion without bundling Pandoc into every client.

Running Pandoc as an MCP tool centralizes conversions, keeps small clients lightweight, and lets you centralize configuration for templates, filters, and resource limits. The server exposes Pandoc-powered conversion tools via the MCP discovery surface so other services and agents can discover and call file-conversion functions programmatically.

Features

• Exposes Pandoc as one or more MCP tools for programmatic conversion
• Supports common readers and writers provided by Pandoc: markdown, docx, html, pdf, epub, latex, and more
• Accepts file uploads (binary input) and returns converted file bytes
• Configurable Pandoc command, template paths, and conversion options
• Optional Docker image for quick deployment
• Simple error reporting and size limits to protect the service

Installation / Configuration

Prerequisites

• Python 3.9+ (server component)
• Pandoc CLI installed and available in PATH or configured path
• (Optional) Docker, if you prefer containerized deployment

Clone the repository and create a virtual environment:

git clone https://github.com/Klavis-AI/klavis.git
cd klavis/mcp_servers/pandoc
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Install Pandoc

• macOS (Homebrew):

brew install pandoc

• Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y pandoc

• Windows: download the Pandoc installer from https://pandoc.org/installing.html

Environment variables

Example environment file (.env) you can adapt:

MCP_HOST=0.0.0.0
MCP_PORT=8080
PANDOC_PATH=/usr/bin/pandoc       # optional if pandoc is in PATH
MAX_UPLOAD_MB=50
LOG_LEVEL=info

Start the server (example using a Python entrypoint):

export $(cat .env | xargs)   # or set env vars individually
python -m mcp_pandoc.server   # replacement for your server entrypoint

Docker (example)

A simple Dockerfile is provided in the repo. Build and run:

docker build -t mcp-pandoc .
docker run -p 8080:8080 -e MCP_PORT=8080 mcp-pandoc

Adjust environment variables in your docker run or Docker Compose file.

Available Resources

The server exposes one or more MCP tools for conversion. The exact tool names are discoverable via your MCP client (MCP discovery), but typical resources include:

• Tool: pandoc.convert
  • Inputs: file bytes (uploaded), input_format (string), output_format (string), pandoc_args (optional array)
  • Output: converted file bytes, mime type, filename suggestion

Common supported formats (depends on your Pandoc install and extensions):

Note: PDF generation sometimes requires a PDF engine (wkhtmltopdf, weasyprint, or LaTeX) depending on your Pandoc configuration.

Use Cases

1. Convert Markdown to DOCX for client download

curl -X POST "http://localhost:8080/convert" \
  -F "[email protected]" \
  -F "input_format=markdown" \
  -F "output_format=docx" \
  --output notes.docx

2. Generate a PDF from a Markdown document using custom Pandoc args

curl -X POST "http://localhost:8080/convert" \
  -F "[email protected]" \
  -F "input_format=markdown" \
  -F "output_format=pdf" \
  -F 'pandoc_args=["--pdf-engine=xelatex","-V","geometry:margin=1in"]' \
  --output report.pdf

3. Use as a programmatic tool inside an agent/workflow

• A language model produces Markdown content as part of a workflow.
• The agent sends the Markdown bytes to the MCP pandoc.convert tool with output_format=docx.
• The returned DOCX bytes are saved and delivered to the end user.

4. Batch conversions

• Upload a zip of Markdown files, iterate server-side (or via the MCP tool) to convert each file into a target format, and return a zip of converted outputs. The server can be extended with batch helper utilities for this pattern.

Error handling and limits

• The server enforces configurable upload size limits (e.g., MAX_UPLOAD_MB). Large conversions should be paged or pre-validated.
• If Pandoc fails, the server will return diagnostic output (exit code and stderr) to help debug missing templates or unsupported formats.
• For PDF output, ensure your Pandoc