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

Un servidor simple y confiable del Protocolo de Contexto de Modelo (MCP) que convierte archivos Markdown en documentos profesionales de Word (.docx) y PDF, con soporte completo para plantillas .dotx.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP-MD-PDF: Convertidor de Markdown a Word/PDF

Un servidor de Model Context Protocol (MCP) simple y confiable que convierte archivos Markdown en documentos profesionales de Word (.docx) y PDF — con soporte completo para plantillas .dotx.

Antecedentes

Esta herramienta nació de una necesidad práctica. A menudo escribimos documentación, guías y notas técnicas en Markdown — es rápido, ligero y fácil de versionar. Pero cuando llega el momento de entregar estos archivos a clientes o presentarlos de forma profesional, normalmente queremos que coincidan con el estilo de nuestro proyecto o empresa: diseño limpio, fuentes consistentes, portada con marca y formato pulido.

Así que, en lugar de hacerlo manualmente cada vez, creamos un flujo sencillo:

Convertir Markdown → Word (.docx usando una plantilla .dotx) → PDF

Al usar plantillas de Word, pudimos aplicar nuestro propio diseño una sola vez y mantener todos los documentos consistentes. De ahí surgió este pequeño proyecto: una forma rápida de convertir Markdown en documentos hermosos y listos para compartir que parezcan parte de tu organización.

Características

🚀 Conversión rápida – De Markdown a Word o PDF en segundos
🎨 Soporte de plantillas – Aplica plantillas .dotx para un estilo consistente y con marca
📦 Procesamiento por lotes – Convierte múltiples archivos a la vez
🔧 Salida flexible – Elige entre .docx, .pdf o ambos
🤖 Listo para IA – Diseñado para integrarse sin problemas con Claude y otras herramientas de IA compatibles con MCP

Instalación

Elige el método de instalación que mejor se adapte a tus necesidades:

Método	¿Descarga de código?	Soporte PDF	Ideal para
uvx (Opción 1)	❌ No	✅ Sí (requiere LibreOffice)	Usuarios de Claude Desktop
pip (Opción 2)	❌ No	✅ Sí (requiere LibreOffice)	Usuarios de paquetes Python
Desde el código fuente (Opción 3)	✅ Sí	✅ Sí (requiere LibreOffice)	Desarrolladores

Opción 1: Usando `uvx` (Recomendado - Sin necesidad de descargar código)

Ideal para: Usuarios de Claude Desktop que quieren la instalación más simple.

Requisitos:

Python 3.10+
Para conversión a PDF:
- Windows: Microsoft Word (usa automatización COM)
- macOS: LibreOffice (brew install --cask libreoffice)
- Linux: LibreOffice (sudo apt-get install libreoffice)

Instalación:

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

Configuración de Claude Desktop:

Añade a tu claude_desktop_config.json:

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

Reinicia Claude Desktop para que los cambios surtan efecto.

📖 Consulta la sección de Configuración para conocer la ubicación del archivo de configuración y configuraciones alternativas.

Opción 2: Usando `pip` (Sin necesidad de descargar código)

Ideal para: Usuarios que quieren instalar como paquete de Python.

Requisitos:

Python 3.10+
Para conversión a PDF (igual que la Opción 1):
- Windows: Microsoft Word
- macOS/Linux: LibreOffice

Instalación:

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

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

Configuración de Claude Desktop:

Añade a tu claude_desktop_config.json:

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

Reinicia Claude Desktop para que los cambios surtan efecto.

📖 Consulta la sección de Configuración para conocer la ubicación del archivo de configuración y configuraciones alternativas.

Opción 3: Desde el código fuente (Requiere descarga de código)

Ideal para: Desarrolladores que quieren modificar el código o contribuir.

Requisitos:

Git
Python 3.10+
Para conversión a PDF (igual que arriba)

Instalación:

# 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]"

Configuración de Claude Desktop:

Añade a tu claude_desktop_config.json:

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

Reinicia Claude Desktop para que los cambios surtan efecto.

📖 Consulta la sección de Configuración para conocer la ubicación del archivo de configuración y configuraciones alternativas.

Configuración

Paso 1: Encuentra tu archivo de configuración

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

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

Paso 2: Añade el servidor MCP

Abre el archivo de configuración y añade el servidor mcp-md-pdf:

Opción A: Usando uvx (Recomendado)

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

Opción B: Instalación local

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

Opción C: Con variables de entorno

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

Paso 3: Reinicia Claude Desktop

Cierra y vuelve a abrir Claude Desktop para que los cambios surtan efecto.

Uso

Con Claude Desktop

Después de la configuración, reinicia Claude Desktop y simplemente pide:

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

Herramientas MCP

1. `convert_markdown`

Convierte un solo archivo Markdown a Word o PDF.

Parámetros:

markdown_path (str) – Ruta al archivo .md
output_path (str) – Ruta base de salida (sin extensión)
output_format (str) – "docx", "pdf" o "both" (predeterminado: "docx")
template_path (str, opcional) – Ruta a la plantilla .dotx

Ejemplos:

# 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`

Convierte múltiples archivos Markdown a la vez.

Parámetros:

markdown_files (list[str]) – Lista de archivos .md
output_dir (str) – Directorio de salida
output_format (str) – "docx", "pdf" o "both"
template_path (str, opcional) – Plantilla .dotx compartida

Ejemplo:

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

3. `list_supported_formats`

Lista los formatos compatibles y sus capacidades.

Características de Markdown compatibles

Característica	Compatible	Notas
Encabezados (H1–H6)	✅	`#` hasta `######`, con respaldo de plantilla
Negrita / Cursiva	✅	Sintaxis estándar de Markdown
Código en línea	✅	Monoespaciado con fondo gris
Bloques de código	✅	Estilo profesional con fondo y bordes
Listas con viñetas y numeradas	✅	Anidadas hasta 3 niveles
Tablas	✅	Con estilo de encabezado y formato en línea
Citas en bloque	✅	Texto en cursiva con borde izquierdo y sombreado de fondo
Reglas horizontales	✅	`---`
Unicode y Emoji	✅	Soporte completo UTF-8

Para un análisis detallado de la cobertura de características, consulta docs/MARKDOWN_COVERAGE.md

Soporte de plantillas

Usa una plantilla de Word .dotx para definir el estilo de tu documento:

Encabezados, fuentes y colores personalizados
Márgenes de página y diseño
Encabezados y pies de página
Marca y colocación de logotipos
Formato de tabla de contenidos

Si no se proporciona una plantilla, se utiliza un diseño predeterminado limpio.

Configuración de conversión a PDF

Importante: La conversión a PDF requiere LibreOffice (o Microsoft Word en Windows) para preservar todo el formato DOCX.

¿Por qué LibreOffice?

LibreOffice es necesario para la conversión a PDF porque preserva TODO el formato de los archivos DOCX:

✅ Colores, fondos, bordes - Estilo profesional intacto
✅ Bloques de código - Resaltado de sintaxis y fondos preservados
✅ Tablas - Encabezados, bordes y estilo de celdas mantenidos
✅ Estilos de plantilla - El formato de plantilla .dotx se traslada al PDF
✅ Fuentes y espaciado - La tipografía permanece perfecta en píxeles

Los enfoques alternativos (Pandoc, etc.) pierden formato - tratan el DOCX como marcado de texto plano, eliminando los estilos visuales durante la conversión a PDF.

Conversión a DOCX (todas las plataformas)

✅ Funciona de inmediato - ¡no se necesita software adicional!

Conversión a PDF (específica por plataforma)

Usuarios de Windows

Opción A: Microsoft Word (Mejor para Windows)

Si tienes Microsoft Word instalado:

# Install Python COM automation library
pip install pywin32

¡Eso es todo! El convertidor usará automáticamente Word para la conversión a PDF.

Opción B: LibreOffice (Recomendado si no tienes 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

Verifica la instalación:

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

Usuarios de macOS

LibreOffice es OBLIGATORIO para la conversión a PDF en macOS (no hay soporte nativo de COM de MS Word).

Instalación (elige un método):

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

Requisitos del sistema:

macOS 10.15 (Catalina) o posterior
~800 MB de espacio en disco
Funciona tanto en Intel como en Apple Silicon (M1/M2/M3)

Verifica la instalación:

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

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

Usuarios de Linux

Ubuntu/Debian (método recomendado):

# 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

Para servidores sin interfaz gráfica (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

Verifica la instalación:

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

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

Notas de plataforma

Conversión a DOCX: Funciona en todas las plataformas (Windows, macOS, Linux) - no se requiere software adicional
Conversión a PDF: Multiplataforma con detección automática de plataforma:
- Windows: Usa Microsoft Word (si está instalado) o LibreOffice
- macOS/Linux: Usa LibreOffice en modo sin interfaz gráfica

¿Por qué LibreOffice para PDF? LibreOffice preserva TODO el formato DOCX al convertir a PDF:

✅ Colores, fondos y bordes
✅ Estilo profesional de bloques de código (fondos #F5F5F5)
✅ Bordes de citas en bloque (borde izquierdo azul)
✅ Encabezados de tabla con fondos de color
✅ Estilos de plantilla de archivos .dotx
✅ Fuentes, espaciado y diseño

Requisitos

Python 3.10+
Pillow (manejo de imágenes)
python-docx (generación de Word)
pywin32 (solo Windows)
fastmcp (framework MCP)

Desarrollo

# 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/

Pruebas

Cubre:

Conversión de Markdown → Word
Aplicación de plantillas
Herramientas del servidor MCP
Unicode, emoji y casos límite

Estructura:

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

Ejemplos

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

O inspecciona mediante:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

Ejemplo de uso:

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)

Solución de problemas

El servidor no aparece en Claude Desktop

Verifica que claude_desktop_config.json sea JSON válido (sin comas finales)
Comprueba que la ruta de Python sea correcta para tu sistema
Revisa los registros de Claude Desktop:
- Windows: %APPDATA%\Claude\logs\
- macOS: ~/Library/Logs/Claude/
Reinicia Claude Desktop por completo

Problemas con la ruta de Python

Verifica tu instalación de Python:

python --version
# or
python3 --version

Si el comando no funciona, encuentra tu ruta de Python:

Windows: where python
macOS/Linux: which python3

Actualiza el archivo de configuración con la ruta correcta.

La conversión a PDF falla

Error: pywin32 library required for PDF conversion on Windows

Solución (Windows):

pip install pywin32

Error: LibreOffice not found

Solución (macOS):

brew install --cask libreoffice

Solución (Ubuntu/Debian):

sudo apt-get install libreoffice libreoffice-writer

Solución (Fedora):

sudo dnf install libreoffice

La plantilla no se carga

Error: Archivo .dotx inválido o faltante

Solución:

Verifica que la ruta y la extensión del archivo sean correctas
Asegúrate de que el archivo de plantilla exista y sea accesible
Prueba la conversión sin plantilla para aislar el problema

Errores de importación

Error: ModuleNotFoundError: No module named 'fastmcp'

Solución:

Ejecuta pip install -e . desde el directorio del proyecto
O instala desde PyPI: pip install mcp-md-pdf

Pruebas con MCP Inspector

Para depuración avanzada, prueba el servidor directamente:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

Esto abre una interfaz web para interactuar con las herramientas MCP directamente.

Licencia

Licencia MIT – consulta el archivo LICENSE.

Contribuciones

Las solicitudes de extracción (pull requests) son bienvenidas. Si tienes ideas para mejorar las conversiones, las plantillas o nuevos formatos, nos encantaría verlas.

Créditos

Construido con ❤️ usando el framework FastMCP — creado para que los documentos Markdown parezcan informes reales, no solo texto en GitHub.

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

Documentación

MCP-MD-PDF: Convertidor de Markdown a Word/PDF

Antecedentes

Características

Instalación

Opción 1: Usando uvx (Recomendado - Sin necesidad de descargar código)

Opción 2: Usando pip (Sin necesidad de descargar código)

Opción 3: Desde el código fuente (Requiere descarga de código)

Configuración

Paso 1: Encuentra tu archivo de configuración

Paso 2: Añade el servidor MCP

Paso 3: Reinicia Claude Desktop

Uso

Con Claude Desktop

Herramientas MCP

1. convert_markdown

2. convert_markdown_batch

3. list_supported_formats

Características de Markdown compatibles

Soporte de plantillas

Configuración de conversión a PDF

¿Por qué LibreOffice?

Conversión a DOCX (todas las plataformas)

Conversión a PDF (específica por plataforma)

Usuarios de Windows

Usuarios de macOS

Usuarios de Linux

Notas de plataforma

Requisitos

Desarrollo

Pruebas

Ejemplos

Solución de problemas

El servidor no aparece en Claude Desktop

Problemas con la ruta de Python

La conversión a PDF falla

La plantilla no se carga

Errores de importación

Pruebas con MCP Inspector

Licencia

Contribuciones

Créditos

Opción 1: Usando `uvx` (Recomendado - Sin necesidad de descargar código)

Opción 2: Usando `pip` (Sin necesidad de descargar código)

1. `convert_markdown`

2. `convert_markdown_batch`

3. `list_supported_formats`