Cómo usar MarkItDown con Claude

Publicado el 29 de agosto de 2026

MarkItDown es una herramienta de Microsoft que convierte casi cualquier documento a Markdown. Su utilidad real aparece cuando la conectas a Claude: en vez de pegar el contenido de un PDF a mano, el modelo accede al documento ya convertido y con la estructura intacta.

Qué es MarkItDown

MarkItDown es una utilidad de código abierto escrita en Python que toma un archivo de entrada y devuelve su contenido en Markdown. Admite PDF, documentos de Word, hojas de Excel, presentaciones de PowerPoint, HTML, CSV, JSON, XML, imágenes y audio, entre otros.

La diferencia con un conversor cualquiera está en el objetivo. MarkItDown no busca reproducir el diseño del documento original, sino conservar su estructura semántica: encabezados, listas, tablas, enlaces y énfasis. Todo lo que es decorativo se descarta. El resultado no sirve para imprimir, pero es exactamente lo que necesita un modelo de lenguaje para entender un documento.

El proyecto está mantenido por Microsoft y disponible en github.com/microsoft/markitdown.

Por qué convertir documentos a Markdown antes de dárselos a la IA

Cuando le pasas un PDF directamente a un modelo, este tiene que lidiar con columnas, cabeceras repetidas, numeración de páginas y saltos de línea arbitrarios. Buena parte de esa basura acaba consumiendo contexto sin aportar nada.

Markdown resuelve tres problemas a la vez, y son los mismos que explicamos en Markdown en prompts.

• Estructura explícita: un ## le dice al modelo que empieza una sección. En un PDF, un encabezado es solo texto que resulta estar en negrita y a mayor tamaño.
• Menos tokens: sin etiquetas ni metadatos de formato, el mismo contenido ocupa bastante menos.
• Tablas legibles: una tabla Markdown se lee de corrido. Una tabla extraída de un PDF suele llegar como una lista de celdas sin relación aparente.

Los modelos de lenguaje generan Markdown de forma nativa, así que también lo interpretan mejor que ningún otro formato. Esa es la idea de fondo que desarrollamos en Markdown y la inteligencia artificial.

Instalar MarkItDown

Necesitas Python instalado en el sistema. La instalación se hace con el gestor de paquetes habitual, incluyendo las dependencias opcionales para que soporte todos los formatos.

pip install 'markitdown[all]'

Si prefieres aislar la herramienta del resto de tu entorno de Python, puedes usar pipx o uv, que la instalan como un comando independiente.

uv tool install 'markitdown[all]'

Comprueba que ha funcionado pidiéndole la ayuda del comando.

markitdown --help

Convertir archivos desde la terminal

El uso más simple es pasarle un archivo y redirigir la salida a un .md.

markitdown informe.pdf > informe.md

También admite indicar el archivo de salida con una opción, que es más cómodo cuando encadenas comandos.

markitdown presentacion.pptx -o presentacion.md

Y funciona leyendo de la entrada estándar, lo que permite combinarlo con otras herramientas en una tubería.

cat documento.docx | markitdown

Para convertir una carpeta entera basta con un bucle del shell, porque la herramienta trabaja archivo a archivo.

for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done

Usar MarkItDown desde Python

Si lo que quieres es integrarlo en un script propio, la API es directa y devuelve un objeto con el texto convertido.

from markitdown import MarkItDown

md = MarkItDown()
resultado = md.convert("informe.pdf")
print(resultado.text_content)

Esto resulta útil para montar tuberías de preprocesado antes de enviar documentos a un modelo, por ejemplo dentro de un sistema de recuperación de información donde necesitas trocear el contenido por secciones.

Formatos que admite

La lista cambia según la versión y las dependencias opcionales que hayas instalado, así que conviene revisar el repositorio oficial para el estado actual. A grandes rasgos cubre estos grupos.

En imágenes y audio, la calidad del resultado depende de servicios adicionales. Para describir imágenes puede apoyarse en un modelo de lenguaje, y para el audio necesita un motor de transcripción. Sin esas piezas configuradas, extrae lo que puede y poco más.

Cómo conectar MarkItDown a Claude

Aquí es donde la herramienta pasa de ser un conversor más a algo realmente útil. MarkItDown se distribuye también como servidor MCP, el protocolo que permite a Claude usar herramientas externas. Una vez conectado, Claude convierte los documentos por su cuenta cuando los necesita.

Instalar el servidor MCP

El servidor viene en un paquete propio, separado de la herramienta de línea de comandos.

pip install markitdown-mcp

Configurar Claude Desktop

Claude Desktop lee su configuración de un archivo llamado claude_desktop_config.json. En macOS está en ~/Library/Application Support/Claude/ y en Windows en %APPDATA%\Claude\. Si no existe, créalo.

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

Guarda el archivo y reinicia Claude Desktop por completo, no basta con cerrar la ventana. Al volver a abrirlo deberías ver la herramienta disponible en el indicador de conexiones.

El comando exacto puede variar según cómo hayas instalado el paquete y según la versión del servidor, así que si no aparece, consulta el README del repositorio oficial para la configuración vigente.

Usarlo en Claude Code

Si trabajas desde la terminal con Claude Code, no hace falta editar ningún JSON a mano. El propio cliente tiene un comando para registrar servidores MCP.

claude mcp add markitdown -- markitdown-mcp

A partir de ahí el agente puede convertir documentos dentro de la sesión, lo que encaja bien con un repositorio que ya tenga su AGENTS.md describiendo el proyecto.

Comprobar que funciona

La forma más rápida de verificarlo es pedirle algo concreto sobre un archivo local.

Convierte el archivo ~/documentos/informe-anual.pdf y hazme
un resumen de los puntos principales por seccion.

Si la conexión está bien, Claude te pedirá permiso para usar la herramienta y trabajará sobre el contenido convertido. Si no, responderá que no puede acceder a archivos locales.

Qué puedes pedirle a Claude una vez conectado

Con el servidor activo desaparece el paso manual de copiar y pegar, y eso abre flujos que antes eran incómodos.

• Resumir informes largos sin recortar el PDF a mano ni preocuparte por el límite de la caja de texto.
• Extraer tablas de hojas de cálculo y pedirle que las devuelva como tablas Markdown listas para pegar en tu documentación.
• Comparar varios documentos pasándole las rutas de todos a la vez.
• Convertir presentaciones en notas, que es especialmente cómodo para apuntes de clase o actas de reunión.
• Pasar documentación antigua a Markdown como primer paso para migrarla a un sitio estático o a una wiki.

Limitaciones que conviene conocer

MarkItDown es una herramienta de extracción, no un traductor perfecto, y conviene saber dónde falla antes de confiar en ella.

• Los PDF complejos se resisten: documentos a varias columnas, con notas al margen o escaneados sin capa de texto dan resultados pobres o directamente vacíos.
• El diseño se pierde por completo, y esto es intencionado. Si necesitas conservar la maquetación, esta no es tu herramienta.
• Las tablas fusionadas se aplanan: las celdas combinadas de Excel o Word no tienen equivalente en Markdown y salen como puedan.
• Imágenes y audio dependen de servicios externos, así que sin configurarlos el resultado es limitado.
• Los documentos muy largos siguen sin caber: convertir un libro entero reduce mucho los tokens, pero no hace milagros con la ventana de contexto.

Una recomendación práctica: revisa siempre el Markdown resultante antes de tomarlo por bueno, sobre todo si vas a construir algo encima. Es texto plano y se corrige en cualquier editor.

Alternativas a MarkItDown

No es la única forma de llegar al mismo sitio, y según el caso hay opciones mejores.

• Pandoc: el conversor universal de documentos. Más potente y configurable para conversiones entre formatos concretos, aunque menos orientado a preparar texto para modelos de lenguaje. Lo cubrimos en nuestra sección de herramientas.
• Nuestros conversores en el navegador: si solo necesitas una conversión puntual y no quieres instalar nada, tienes el conversor de HTML a Markdown funcionando en la propia página.
• Subir el archivo directamente a Claude: para un documento suelto suele ser suficiente y no requiere ninguna instalación. MarkItDown gana cuando el proceso se repite o se automatiza.

La regla es simple: para algo puntual, sube el archivo y listo. Para un flujo recurrente, o cuando quieres controlar exactamente qué texto llega al modelo, monta MarkItDown.

Recursos relacionados

• Guía Markdown de Claude: cómo renderiza Markdown y qué sintaxis admite
• MCP y Markdown: qué es el protocolo que hace posible esta conexión
• Markdown en prompts: por qué estructurar el contexto mejora las respuestas
• Markdown y la inteligencia artificial: el papel del formato en el ecosistema de IA
• AGENTS.md: el estándar para dar contexto a los agentes
• Conversores de Markdown: convertir a PDF, DOCX, HTML y diapositivas sin instalar nada
• Sintaxis de Markdown: la referencia básica del formato