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

Um servidor MCP (Model Context Protocol) simples e confiável que converte arquivos Markdown em documentos profissionais Word (.docx) e PDF — com suporte completo para modelos .dotx.

GitHub

Documentação

MCP-MD-PDF: Conversor de Markdown para Word/PDF

Um servidor Model Context Protocol (MCP) simples e confiável que converte arquivos Markdown em documentos profissionais Word (.docx) e PDF — com suporte completo para templates .dotx.

Contexto

Esta ferramenta nasceu de uma necessidade prática. Frequentemente escrevemos documentação, guias e notas técnicas em Markdown — é rápido, leve e fácil de versionar. Mas quando chega a hora de entregar esses arquivos para clientes ou apresentá-los profissionalmente, geralmente queremos que eles correspondam ao estilo do nosso projeto ou empresa: layout limpo, fontes consistentes, capa com marca e formatação polida.

Então, em vez de fazer isso manualmente toda vez, criamos um fluxo simples:

Converter Markdown → Word (.docx usando um template .dotx) → PDF

Ao usar templates do Word, pudemos aplicar nosso próprio design uma única vez e manter todos os documentos consistentes. Foi daí que surgiu este pequeno projeto — uma maneira rápida de transformar Markdown em documentos bonitos e prontos para compartilhar, que parecem pertencer à sua organização.

Recursos

🚀 Conversão Rápida – De Markdown para Word ou PDF em segundos
🎨 Suporte a Templates – Aplique templates .dotx para uma estilização consistente e com marca
📦 Processamento em Lote – Converta vários arquivos de uma só vez
🔧 Saída Flexível – Escolha entre .docx, .pdf ou ambos
🤖 Pronto para IA – Criado para integrar-se facilmente com Claude e outras ferramentas de IA compatíveis com MCP

Instalação

Escolha o método de instalação que melhor atende às suas necessidades:

Método	Download de Código?	Suporte a PDF	Melhor Para
uvx (Opção 1)	❌ Não	✅ Sim (LibreOffice necessário)	Usuários do Claude Desktop
pip (Opção 2)	❌ Não	✅ Sim (LibreOffice necessário)	Usuários de pacotes Python
A partir do código-fonte (Opção 3)	✅ Sim	✅ Sim (LibreOffice necessário)	Desenvolvedores

Opção 1: Usando `uvx` (Recomendado - Sem Necessidade de Download de Código)

Melhor para: Usuários do Claude Desktop que desejam a instalação mais simples.

Requisitos:

Python 3.10+
Para conversão em PDF:
- Windows: Microsoft Word (usa automação COM)
- macOS: LibreOffice (brew install --cask libreoffice)
- Linux: LibreOffice (sudo apt-get install libreoffice)

Instalação:

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

Configuração do Claude Desktop:

Adicione ao seu claude_desktop_config.json:

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

Reinicie o Claude Desktop para que as alterações tenham efeito.

📖 Consulte a seção de Configuração para saber a localização do arquivo de configuração e configurações alternativas.

Opção 2: Usando `pip` (Sem Necessidade de Download de Código)

Melhor para: Usuários que desejam instalar como um pacote Python.

Requisitos:

Python 3.10+
Para conversão em PDF (igual à Opção 1):
- Windows: Microsoft Word
- macOS/Linux: LibreOffice

Instalação:

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

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

Configuração do Claude Desktop:

Adicione ao seu claude_desktop_config.json:

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

Reinicie o Claude Desktop para que as alterações tenham efeito.

📖 Consulte a seção de Configuração para saber a localização do arquivo de configuração e configurações alternativas.

Opção 3: A partir do Código-Fonte (Requer Download de Código)

Melhor para: Desenvolvedores que desejam modificar o código ou contribuir.

Requisitos:

Git
Python 3.10+
Para conversão em PDF (igual às opções acima)

Instalação:

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

Configuração do Claude Desktop:

Adicione ao seu claude_desktop_config.json:

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

Reinicie o Claude Desktop para que as alterações tenham efeito.

📖 Consulte a seção de Configuração para saber a localização do arquivo de configuração e configurações alternativas.

Configuração

Etapa 1: Encontre Seu Arquivo de Configuração

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

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

Etapa 2: Adicione o Servidor MCP

Abra o arquivo de configuração e adicione o servidor mcp-md-pdf:

Opção A: Usando uvx (Recomendado)

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

Opção B: Instalação Local

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

Opção C: Com Variáveis de Ambiente

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

Etapa 3: Reinicie o Claude Desktop

Feche e reabra o Claude Desktop para que as alterações tenham efeito.

Uso

Com o Claude Desktop

Após a configuração, reinicie o Claude Desktop e simplesmente peça:

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

Ferramentas MCP

1. `convert_markdown`

Converte um único arquivo Markdown para Word ou PDF.

Parâmetros:

markdown_path (str) – Caminho para o arquivo .md
output_path (str) – Caminho base de saída (sem extensão)
output_format (str) – "docx", "pdf" ou "both" (padrão: "docx")
template_path (str, opcional) – Caminho para o template .dotx

Exemplos:

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

Converte vários arquivos Markdown de uma só vez.

Parâmetros:

markdown_files (list[str]) – Lista de arquivos .md
output_dir (str) – Diretório de saída
output_format (str) – "docx", "pdf" ou "both"
template_path (str, opcional) – Template .dotx compartilhado

Exemplo:

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

3. `list_supported_formats`

Lista os formatos suportados e suas capacidades.

Recursos Markdown Suportados

Recurso	Suportado	Observações
Títulos (H1–H6)	✅	`#` até `######`, com fallback para o template
Negrito / Itálico	✅	Sintaxe padrão do Markdown
Código inline	✅	Monoespaçado com fundo cinza
Blocos de código	✅	Estilização profissional com fundo e bordas
Listas com marcadores e numeradas	✅	Aninhadas até 3 níveis
Tabelas	✅	Com estilização de cabeçalho e formatação inline
Citações em bloco	✅	Texto em itálico com borda esquerda e sombreamento de fundo
Regras horizontais	✅	`---`
Unicode e Emoji	✅	Suporte completo a UTF-8

Para uma análise detalhada da cobertura de recursos, consulte docs/MARKDOWN_COVERAGE.md

Suporte a Templates

Use um template Word .dotx para definir o estilo do seu documento:

Títulos, fontes e cores personalizados
Margens e layout da página
Cabeçalhos e rodapés
Marca e posicionamento de logotipo
Formatação de sumário

Se nenhum template for fornecido, um design padrão limpo será usado.

Configuração da Conversão para PDF

Importante: A conversão para PDF requer LibreOffice (ou Microsoft Word no Windows) para preservar toda a formatação do DOCX.

Por que o LibreOffice?

O LibreOffice é necessário para a conversão em PDF porque preserva TODA a formatação dos arquivos DOCX:

✅ Cores, fundos, bordas - Estilização profissional intacta
✅ Blocos de código - Realce de sintaxe e fundos preservados
✅ Tabelas - Cabeçalhos, bordas e estilização de células mantidos
✅ Estilos de template - A formatação do template .dotx é mantida até o PDF
✅ Fontes e espaçamento - Tipografia permanece perfeita em pixels

Abordagens alternativas (Pandoc, etc.) perdem formatação - elas tratam o DOCX como marcação de texto simples, removendo estilos visuais durante a conversão para PDF.

Conversão DOCX (Todas as Plataformas)

✅ Funciona imediatamente - nenhum software adicional necessário!

Conversão PDF (Específica por Plataforma)

Usuários Windows

Opção A: Microsoft Word (Melhor para Windows)

Se você tiver o Microsoft Word instalado:

# Install Python COM automation library
pip install pywin32

Pronto! O conversor usará automaticamente o Word para a conversão em PDF.

Opção B: LibreOffice (Recomendado se não tiver o 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

Verifique a instalação:

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

Usuários macOS

O LibreOffice é OBRIGATÓRIO para conversão em PDF no macOS (não há suporte nativo a COM do MS Word).

Instalação (Escolha um 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 do sistema:

macOS 10.15 (Catalina) ou mais recente
~800 MB de espaço em disco
Funciona em Intel e Apple Silicon (M1/M2/M3)

Verifique a instalação:

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

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

Usuários 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 headless (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

Verifique a instalação:

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

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

Observações por Plataforma

Conversão DOCX: Funciona em todas as plataformas (Windows, macOS, Linux) - nenhum software adicional necessário
Conversão PDF: Multiplataforma com detecção automática de plataforma:
- Windows: Usa Microsoft Word (se instalado) ou LibreOffice
- macOS/Linux: Usa LibreOffice em modo headless

Por que LibreOffice para PDF? O LibreOffice preserva TODA a formatação do DOCX ao converter para PDF:

✅ Cores, fundos e bordas
✅ Estilização profissional de blocos de código (fundos #F5F5F5)
✅ Bordas de citações em bloco (borda esquerda azul)
✅ Cabeçalhos de tabela com fundos coloridos
✅ Estilos de template de arquivos .dotx
✅ Fontes, espaçamento e layout

Requisitos

Python 3.10+
Pillow (manipulação de imagens)
python-docx (geração de Word)
pywin32 (somente Windows)
fastmcp (framework MCP)

Desenvolvimento

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

Testes

Cobrem:

Conversão Markdown → Word
Aplicação de templates
Ferramentas do servidor MCP
Unicode, emoji e casos extremos

Estrutura:

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

Exemplos

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

Ou inspecione via:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

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

Solução de Problemas

Servidor Não Aparece no Claude Desktop

Verifique se claude_desktop_config.json é um JSON válido (sem vírgulas finais)
Confirme se o caminho do Python está correto para o seu sistema
Revise os logs do Claude Desktop:
- Windows: %APPDATA%\Claude\logs\
- macOS: ~/Library/Logs/Claude/
Reinicie o Claude Desktop completamente

Problemas com o Caminho do Python

Verifique sua instalação do Python:

python --version
# or
python3 --version

Se o comando não funcionar, encontre o caminho do seu Python:

Windows: where python
macOS/Linux: which python3

Atualize o arquivo de configuração com o caminho correto.

Falha na Conversão para PDF

Erro: pywin32 library required for PDF conversion on Windows

Correção (Windows):

pip install pywin32

Erro: LibreOffice not found

Correção (macOS):

brew install --cask libreoffice

Correção (Ubuntu/Debian):

sudo apt-get install libreoffice libreoffice-writer

Correção (Fedora):

sudo dnf install libreoffice

Template Não Carregando

Erro: Arquivo .dotx inválido ou ausente

Correção:

Verifique se o caminho e a extensão do arquivo estão corretos
Garanta que o arquivo de template exista e seja acessível
Tente a conversão sem template para isolar o problema

Erros de Importação

Erro: ModuleNotFoundError: No module named 'fastmcp'

Correção:

Execute pip install -e . a partir do diretório do projeto
Ou instale a partir do PyPI: pip install mcp-md-pdf

Testando com o MCP Inspector

Para depuração avançada, teste o servidor diretamente:

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

Isso abre uma interface web para interagir diretamente com as ferramentas MCP.

Licença

Licença MIT – consulte o arquivo LICENSE.

Contribuindo

Pull requests são bem-vindos. Se você tiver ideias para melhorar conversões, templates ou novos formatos, adoraríamos vê-las.

Créditos

Construído com ❤️ usando o framework FastMCP — criado para fazer documentos Markdown parecerem relatórios de verdade, não apenas texto no GitHub.

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

Documentação

MCP-MD-PDF: Conversor de Markdown para Word/PDF

Contexto

Recursos

Instalação

Opção 1: Usando uvx (Recomendado - Sem Necessidade de Download de Código)

Opção 2: Usando pip (Sem Necessidade de Download de Código)

Opção 3: A partir do Código-Fonte (Requer Download de Código)

Configuração

Etapa 1: Encontre Seu Arquivo de Configuração

Etapa 2: Adicione o Servidor MCP

Etapa 3: Reinicie o Claude Desktop

Uso

Com o Claude Desktop

Ferramentas MCP

1. convert_markdown

2. convert_markdown_batch

3. list_supported_formats

Recursos Markdown Suportados

Suporte a Templates

Configuração da Conversão para PDF

Por que o LibreOffice?

Conversão DOCX (Todas as Plataformas)

Conversão PDF (Específica por Plataforma)

Usuários Windows

Usuários macOS

Usuários Linux

Observações por Plataforma

Requisitos

Desenvolvimento

Testes

Exemplos

Solução de Problemas

Servidor Não Aparece no Claude Desktop

Problemas com o Caminho do Python

Falha na Conversão para PDF

Template Não Carregando

Erros de Importação

Testando com o MCP Inspector

Licença

Contribuindo

Créditos

Opção 1: Usando `uvx` (Recomendado - Sem Necessidade de Download de Código)

Opção 2: Usando `pip` (Sem Necessidade de Download de Código)

1. `convert_markdown`

2. `convert_markdown_batch`

3. `list_supported_formats`