Se você está construindo um pipeline de RAG, um assistente com IA, ou qualquer fluxo onde um LLM precisa ler documentos reais, você já esbarrou na mesma parede: seus dados não estão limpos. São um Word de RH, um PDF do fornecedor, um PowerPoint do planejamento do trimestre passado. Nada disso está pronto para um LLM por padrão.
A Microsoft tem uma resposta para isso. MarkItDown é uma biblioteca Python open-source que converte praticamente qualquer formato de documento em Markdown limpo e estruturado — o formato que os LLMs realmente entendem bem. Nasceu dentro da Microsoft Research como ferramenta interna para o framework multi-agente AutoGen, foi publicada como open-source no final de 2024 e desde então acumulou mais de 91.000 estrelas no GitHub. A última versão estável, v0.1.5, saiu em 20 de fevereiro de 2026.
Por que Markdown para LLMs?
Não é arbitrário. Markdown ocupa um lugar intermediário ideal: é próximo ao texto plano (pouco overhead de tokens), mas preserva a estrutura do documento — cabeçalhos, listas, tabelas, links. Os modelos mainstream são treinados extensamente em Markdown e o lidam de forma nativa. Quando você manda para um LLM um PDF cru cheio de espaços em branco desordenados e hierarquia perdida, a qualidade da recuperação cai. Quando você manda Markdown limpo, o chunking, o embedding e as citações funcionam muito melhor.
O trabalho do MarkItDown é tender essa ponte entre o material fonte desordenado e um input confiável para o LLM.
O Que Converte
A biblioteca lida com uma ampla variedade de formatos de entrada:
- Documentos Office: DOCX, PPTX, XLSX, XLS
- PDFs: via pdfminer (PDFs com camada de texto; o OCR requer o plugin)
- Imagens: JPG, PNG — com descrição gerada por LLM quando você fornece um cliente
- Áudio: WAV, MP3 — via transcrição de voz
- Conteúdo web: HTML, URLs
- Dados estruturados: CSV, JSON, XML
- Arquivos comprimidos: ZIP (processa o conteúdo de forma recursiva)
A arquitetura é limpa: cada formato tem uma classe DocumentConverter dedicada, registrada ao iniciar. O processamento ocorre completamente na memória — sem arquivos temporários — o que importa tanto para o desempenho quanto para a segurança.
Como Instalar MarkItDown? (em 4 linhas)
pip install 'markitdown[all]'
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("informe_q4.xlsx")
print(result.text_content)
Isso é tudo. result.text_content te retorna Markdown estruturado, preservando nomes de abas, linhas de tabela e qualquer cabeçalho.
Como Usar MarkItDown a Partir do Terminal?
MarkItDown também vem como ferramenta de linha de comando, útil para pré-processamento em lote:
# Converter um arquivo individual
markitdown documento.pdf -o output.md
# Converter e fazer pipe para outra ferramenta
markitdown reporte.docx | grep "## "
Descrição de Imagens com um Cliente LLM
Para imagens (e áudio), MarkItDown pode chamar um LLM para gerar uma descrição — útil quando você precisa que as imagens dentro de um documento sejam semanticamente pesquisáveis:
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("diagrama_arquitetura.png")
print(result.text_content)
# Retorna uma descrição estruturada do conteúdo da imagem
Isso funciona com qualquer cliente compatível com OpenAI — você não está preso à OpenAI especificamente.
O Plugin de OCR
Para PDFs e arquivos Office que contêm imagens com texto incorporado, o plugin markitdown-ocr estende a biblioteca base com OCR baseado em LLM Vision:
pip install 'markitdown[all]' markitdown-ocr
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("contrato_escaneado.pdf")
print(result.text_content)
Se llm_client não for fornecido, o plugin é carregado, mas silenciosamente volta ao extrator de texto padrão.
Como Conectar MarkItDown ao Claude? (passo a passo)
Uma das incorporações mais interessantes do ciclo v0.1.x: MarkItDown agora vem com um servidor MCP oficial (markitdown-mcp), o que significa que você pode expor a conversão de documentos como uma ferramenta dentro do Claude Desktop ou qualquer cliente compatível com MCP.
Na prática: em vez de pré-processar arquivos manualmente antes de mandá-los ao Claude, sua configuração de MCP lida com a conversão em tempo real. Claude pode chamar MarkItDown, obter Markdown estruturado de volta, e raciocinar sobre o conteúdo sem que você lidasse com a etapa do pipeline de forma manual.
1. Instale o servidor MCP
pip install markitdown-mcp
Teste diretamente do terminal — usa STDIO por padrão:
markitdown-mcp
2. Para Claude Desktop, a Microsoft recomenda a imagem Docker
Constru a imagem a partir do repositório do MarkItDown:
docker build -t markitdown-mcp:latest .
E adicione esta entrada ao seu claude_desktop_config.json:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
}
}
}
3. Se você precisar converter arquivos locais, monte o diretório no contêiner:
docker run -it --rm -v /home/usuario/data:/workdir markitdown-mcp:latest
Tudo que estiver em data fica acessível como /workdir/arquivo.pdf dentro do contêiner.
O servidor expõe uma única ferramenta: convert_to_markdown(uri), que aceita URIs http:, https:, file: e data:.
markitdown-mcpé pensado para uso local, com agentes de confiança. Por padrão se vincula alocalhoste não fica exposto à rede. Não o vincule a outras interfaces sem entender as implicações de segurança.
Onde MarkItDown se Encaixa (e Onde Não)
MarkItDown é a ferramenta correta quando você precisa de conversão rápida e leve para consumo por LLM — pipelines de RAG, indexação de documentos, assistentes de IA que precisam ler arquivos de negócio.
Não é a ferramenta correta quando:
- Você precisa de formato de alta fidelidade para leitores humanos → use Pandoc em vez disso
- Seus documentos são PDFs científicos complexos com tabelas, equações e desafios de ordem de leitura → Docling (IBM) os lida melhor
- Você está construindo um pipeline ETL de documentos em larga escala com 40+ conectores → Unstructured.io é mais apropriado aí
Saber onde termina cada ferramenta é tão útil quanto saber o que ela faz.
v0.1.5: O Que Mudou
A última versão (20 de fevereiro de 2026) atendeu duas dependências de segurança:
- Atualiza
mammothpara 1.11.0 para resolver CVE-2025-11849 - Atualiza
pdfminer.sixpara 20251107 para resolver GHSA-wf5f-4jwr-ppcp
Também em versões recentes: mudança de minidom para defusedxml no parsing de XML — outro movimento de hardening de segurança. Se você está rodando uma versão mais antiga do MarkItDown em qualquer ambiente que processa documentos não confiáveis, vale a pena atualizar.
A Conclusão Prática
A etapa de pré-processamento em pipelines de IA é chata, mas é onde se ganha ou se perde muita qualidade. MarkItDown é uma biblioteca bem mantida, com licença MIT, de um time que a construiu para uso real em produção dentro de um dos maiores grupos de pesquisa de IA do mundo. Ela lida com a camada de conversão desordenada para que você possa se focar no que o LLM faz com os dados.
Instale-a, aponte-a para seu acervo de documentos, e mande para seu LLM algo com o qual ele realmente possa trabalhar.
pip install 'markitdown[all]'
GitHub: microsoft/markitdown
Como você está lidando com o pré-processamento de documentos em seus projetos de IA? Você está construindo algo customizado ou conta com bibliotecas como essa? Compartilhe sua experiência nos comentários 