01 Qué es MarkItDown y qué problema resuelve
MarkItDown es una herramienta de línea de comandos y una librería de Python publicada por Microsoft con licencia MIT. Su único trabajo es coger un archivo y devolver su contenido en Markdown: títulos, listas, tablas y enlaces, sin el envoltorio del formato original.
¿Por qué importa? Un modelo de lenguaje entiende muy bien el Markdown y, al ser casi texto plano, ocupa pocos tokens. Si conviertes antes de leer, Claude recibe solo lo que necesita y le queda más contexto libre para razonar. Además, el resultado se puede guardar, buscar, comparar con diff o reutilizar en otras herramientas.
- ✓PDF, Word (.docx), Excel (.xlsx y .xls) y PowerPoint (.pptx)
- ✓HTML, CSV, JSON y XML
- ✓Imágenes (metadatos EXIF y texto) y audio (metadatos y transcripción)
- ✓Archivos ZIP: recorre lo que hay dentro
- ✓Enlaces de YouTube (transcripción) y libros EPUB
- ✓Mensajes de Outlook, con su extra correspondiente
02 Cuándo compensa y cuándo no
Claude ya sabe leer PDF e imágenes por sí mismo, así que MarkItDown no es obligatorio. Brilla cuando el volumen o el formato complican las cosas. Microsoft lo deja claro: la salida está pensada para análisis por máquinas, no para conversiones con maquetación perfecta.
| Situación | ¿Usar MarkItDown? | Motivo |
|---|---|---|
| Excel con varias hojas o PowerPoint de 60 diapositivas | Sí | Obtienes tablas y texto ordenados sin cargar el archivo binario |
| Carpeta con decenas de contratos o facturas | Sí | Conviertes en lote y Claude trabaja sobre texto que puede buscar |
| Informe en PDF con gráficos donde importa lo visual | No siempre | La conversión se queda con el texto; los gráficos se pierden |
| PDF escaneado (una foto de papel) | Solo con OCR | El conversor básico no saca texto de imágenes incrustadas |
| Un documento corto que vas a leer una vez | Indiferente | El ahorro es pequeño; arrástralo a Claude y listo |
03 Instalación paso a paso
-
1
Comprueba Python
MarkItDown necesita Python entre la 3.10 y la 3.14. Escribe python3 --version en la terminal; si no lo tienes, instálalo desde python.org o con el gestor de paquetes de tu sistema.
-
2
Crea un entorno virtual
El proyecto recomienda aislarlo para no chocar con otras librerías. Un entorno en tu carpeta personal te sirve para todos los proyectos.
-
3
Instala el paquete con todos los formatos
La opción [all] añade las dependencias de PDF, Word, Excel, PowerPoint, audio y YouTube. Si solo quieres algunos, puedes instalar extras sueltos como [pdf, docx, pptx].
-
4
Haz una prueba
Convierte cualquier documento y abre el .md resultante. Si ves títulos y tablas en texto, está listo.
python3 -m venv ~/.venvs/markitdown
source ~/.venvs/markitdown/bin/activate
pip install 'markitdown[all]'
markitdown informe.pdf -o informe.md04 Los comandos que vas a usar
# Guardar el resultado en un archivo
markitdown presupuesto.docx -o presupuesto.md
# Mostrarlo en pantalla o redirigirlo
markitdown ventas.xlsx > ventas.md
# Leer desde una tubería
cat contrato.pdf | markitdown
# Instalar solo los formatos que necesitas
pip install 'markitdown[pdf, docx, xlsx]'Extras por formato
pdf, docx, pptx, xlsx, xls, outlook, audio-transcription y youtube-transcription. Con [all] vienen todos.
Plugins
Están desactivados por defecto. markitdown --list-plugins los muestra y --use-plugins los activa en una conversión.
Azure Document Intelligence
Opción de pago en la nube para PDF escaneados o tablas complejas. Se activa con -d y el endpoint de tu recurso.
Librería de Python
Si programas, MarkItDown().convert('archivo.xlsx') devuelve el Markdown en result.markdown para integrarlo en tus scripts.
05 Cómo conectarlo con Claude Code
Tienes dos caminos. El más simple es dejar que Claude ejecute la CLI cuando le hace falta: basta con que el comando exista y que se lo recuerdes en tu CLAUDE.md. El segundo es registrar el servidor MCP oficial, markitdown-mcp, que expone una herramienta convert_to_markdown capaz de leer rutas locales y URL.
source ~/.venvs/markitdown/bin/activate
pip install markitdown-mcp
claude mcp add --transport stdio markitdown -- ~/.venvs/markitdown/bin/markitdown-mcp06 Prompts listos para usar
Convierte con MarkItDown el archivo ~/Documentos/contrato-proveedor.pdf y guarda el resultado junto al original. Después léelo y dame: 1) partes, objeto y duración; 2) importes y forma de pago; 3) cláusulas de penalización, renovación automática y rescisión, citando el apartado; 4) tres puntos que convendría negociar. Si alguna página sale vacía o ilegible en el Markdown, dímelo.Pasa ~/Documentos/ventas-2026.xlsx a Markdown con MarkItDown. Revisa todas las hojas y dime qué columnas hay en cada una. Luego calcula las ventas por mes y por producto, señala los tres productos que más crecen y los que caen, y avísame si ves filas duplicadas o celdas vacías que puedan falsear los totales.En la carpeta ~/Documentos/facturas hay PDF de proveedores. Conviértelos todos con MarkItDown a una subcarpeta markdown/ sin tocar los originales. Después crea una tabla CSV con proveedor, número de factura, fecha, base imponible, IVA y total. Marca en una columna aparte las facturas en las que no estés seguro de algún dato.07 Límites y seguridad
- ✓Los PDF escaneados necesitan OCR: el plugin markitdown-ocr usa un modelo con visión compatible con la API de OpenAI, o Azure Document Intelligence
- ✓Las descripciones automáticas de imágenes también requieren un cliente de modelo de lenguaje configurado
- ✓La transcripción de audio del extra básico solo cubre WAV y MP3
- ✓Los gráficos y la maquetación no se conservan: revisa el original si el formato importa
- ✓Comprueba siempre los totales de tablas convertidas antes de tomar decisiones con ellos
Preguntas frecuentes
Sí. Es software libre de Microsoft con licencia MIT. Solo pagarías si activas servicios opcionales de Azure, como Document Intelligence.
Normalmente sí, porque Claude recibe texto estructurado en lugar del archivo completo. El ahorro depende del documento: es grande en Excel y presentaciones extensas y pequeño en textos cortos.
Sí, es un paquete de Python. Cambia la activación del entorno virtual por la de Windows (la carpeta Scripts en lugar de bin) y el resto de comandos es igual.
Puedes convertir los archivos en tu ordenador y subir el .md al chat. Para que Claude lo ejecute solo necesitas Claude Code o una aplicación compatible con MCP.
Casi siempre es un documento escaneado. Usa un OCR (el plugin markitdown-ocr o Azure) o pásale el PDF directamente a Claude, que puede leer la imagen.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.