MarkItDown MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Amplo suporte de formatos: PDF, DOCX, PPTX, XLSX, HTML, EPub, ZIP, MP3, JPG
OCR de imagens + descrição via hook de LLM opcional
Transcrição de áudio via OpenAI Whisper (opcional)
Busca de URL integrada — passe http://… diretamente
Preserva tabelas, títulos e estrutura básica

Demo ao vivo

Como fica na prática

markitdown-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "markitdown-mcp",
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "markitdown-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "markitdown-mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add markitdown-mcp -- uvx markitdown-mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: MarkItDown MCP

Colocar um PDF de 200 páginas na frente do Claude como Markdown legível

👤 Pesquisadores, advogados, qualquer pessoa com fluxos de trabalho com muitos PDFs ⏱ ~15 min beginner

Quando usar: Você precisa discutir detalhes de um PDF e não quer copiar e colar páginas.

Fluxo

Converter

Use markitdown. Convert ~/Downloads/whitepaper.pdf to Markdown. Tell me total length and section count.✓ Copiado

→ Markdown retornado com resumo do sumário
Discutir detalhes específicos

From section 3, what claims do they make about throughput? Quote the exact lines.✓ Copiado

→ Citações diretas com referências de seção
Comparar com outro documento

Now convert competitor.pdf the same way. Compare their throughput claims.✓ Copiado

→ Tabela de afirmações por documento

Resultado: Dois PDFs ingeridos, comparados e citáveis no chat.

Armadilhas

PDFs digitalizados saem vazios — O MarkItDown faz OCR básico — para PDFs somente com imagem, execute OCR upstream primeiro

Combine com: filesystem

Converter qualquer URL em Markdown limpo sem scraping de navegador

👤 Qualquer pessoa que queira ingerir artigos ou documentos por URL ⏱ ~10 min beginner

Quando usar: O artigo é renderizado dinamicamente ou está atrás de paywall; você quer saída estruturada, não HTML bruto.

Fluxo

Buscar e converter

Use markitdown to convert https://example.com/long-article. Strip nav and footer.✓ Copiado

→ Corpo do artigo em Markdown
Resumir ou citar

Give me the core claim and the strongest evidence cited.✓ Copiado

→ Resumo estruturado

Resultado: URL transformada em Markdown de qualidade para raciocínio.

Armadilhas

SPAs com muito JavaScript retornam vazias — Use um MCP baseado em navegador (browser-act, mcp-chrome) para SPAs e depois passe para o markitdown

Converter em lote uma pasta de documentos Office mistos para uma base de conhecimento

👤 Equipes de operações de conhecimento e suporte construindo corpora internas ⏱ ~30 min intermediate

Quando usar: Você tem uma pasta do Dropbox/SharePoint com documentos mistos e quer que todos sejam legíveis.

Fluxo

Fazer inventário

List ~/docs/ — group by extension. How many PDFs, DOCXs, PPTXs?✓ Copiado

→ Contagens por extensão
Converter todos

Convert every doc in ~/docs/ to Markdown into ~/docs-md/. Preserve folder structure.✓ Copiado

→ Árvore espelhada com arquivos .md
Indexar para recuperação

Now give me a single index.md listing each doc's title and 2-line summary.✓ Copiado

→ Arquivo de índice da base de conhecimento

Resultado: Pasta com formatos mistos transformada em corpus Markdown homogênea.

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

markitdown-mcp + filesystem

Ler arquivos fonte e converter em lote

List ~/inbox/, convert each via markitdown, save to ~/processed/.✓ Copiado

markitdown-mcp + office-word-mcp

Converter documento Word para Markdown para edição e depois converter de volta

MarkItDown the .docx → edit the .md → use word-mcp to write a new .docx with the edits.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
convert_to_markdown	uri (file:// or http://)	Qualquer documento que você queira como texto	0 (hooks de LLM opcionais, pagos)

Custo e limites

O que custa rodar

Cota de API: N/A — local
Tokens por chamada: Variável — PDFs grandes podem gerar dezenas de milhares de linhas de Markdown
Monetário: Gratuito (MIT). Hooks opcionais de LLM/Whisper cobrados separadamente.
Dica: Pule apêndices grandes — converta intervalos de páginas se o SDK suportar para seu tipo de arquivo

Segurança

Permissões, segredos, alcance

Escopos mínimos: filesystem-read outbound:url-fetch

Armazenamento de credenciais: Nenhum por padrão; hooks de LLM precisam de suas próprias chaves

Saída de dados: URLs que você pede para buscar; endpoints de LLM se hooks habilitados

Se você habilitar a descrição de imagem por LLM, suas imagens irão para aquele provedor

Solução de problemas

Erros comuns e correções

ImportError em formato raro

O MarkItDown tem extras opcionais: pip install markitdown[all] para incluir parsers como youtube/azure-docs

Erros de codificação em DOCs legados

Ressalve no Office como DOCX antes de converter; o suporte a .doc é best-effort

Tabelas aparecem comprimidas

O MarkItDown preserva a estrutura da tabela, mas o Claude pode precisar de prompt explícito para renderizar — peça o modo de tabela HTML

Alternativas

MarkItDown MCP vs. outros

Alternativa	Quando usar	Troca
Docling / Unstructured	Você precisa de fidelidade de layout de PDF para documentos científicos complexos	Dependências mais pesadas; mais preciso em tabelas
kreuzberg	Extração de texto pura com OCR em documentos digitalizados	Objetivo de otimização diferente

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills