MarkItDown: deja de quemar tokens con PDFs

⭐ 168,000 estrellas en GitHub · Microsoft · MIT License · Gratis

github.com/microsoft/markitdown

1. Qué es MarkItDown

MarkItDown es una herramienta de línea de comandos y librería de Python creada por Microsoft que convierte archivos de cualquier formato a texto limpio en Markdown. Fue diseñada específicamente para alimentar modelos de lenguaje como Claude — no para consumo humano, sino para que la IA pueda leer documentos de forma eficiente.

Ahorro real de tokens por tipo de documento

Nota: los valores son estimados basados en el contenido promedio de cada tipo de documento. Los PDFs con muchas imágenes o tablas complejas pueden consumir significativamente más tokens.

2. Instalación — 2 minutos desde cero

Opción A — Instalación completa (recomendada)

Instala MarkItDown con soporte para todos los formatos de archivo:

pip install 'markitdown[all]'

Opción B — Instalación selectiva

Si solo necesitas convertir ciertos formatos, instala solo los necesarios:

# Solo PDF y Word
pip install 'markitdown[pdf,docx]'
# Solo Excel y PowerPoint
pip install 'markitdown[xlsx,pptx]'
# Solo PDF
pip install 'markitdown[pdf]'

Verifica que la instalación fue exitosa

markitdown --version

Si ves un número de versión (actualmente 0.1.6), la instalación fue exitosa.

3. Cómo usarlo — Línea de comandos

MarkItDown funciona desde la terminal con comandos simples. Una vez instalado, abres tu terminal, navegas a donde está tu archivo y ejecutas el comando correspondiente.

Convertir un archivo y ver el resultado en pantalla

markitdown mi-documento.pdf

Convertir y guardar como archivo .md

markitdown mi-documento.pdf -o mi-documento.md
# Lo mismo para cualquier formato:
markitdown reporte.xlsx -o reporte.md
markitdown presentacion.pptx -o presentacion.md
markitdown contrato.docx -o contrato.md

Convertir una URL de YouTube (extrae la transcripción)

markitdown https://www.youtube.com/watch?v=XXXX -o transcripcion.md

Convertir varios archivos en secuencia

# Mac / Linux
for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done
# Windows (PowerShell)
Get-ChildItem *.pdf | ForEach-Object { markitdown $_.Name -o ($_.BaseName + '.md') }

4. Uso desde Python — Para automatizar

Si quieres integrar MarkItDown en un script o flujo de trabajo automatizado, puedes usarlo directamente desde Python con unas pocas líneas de código.

Conversión básica en Python

from markitdown import MarkItDown
# Inicializar
md = MarkItDown()
# Convertir un archivo
resultado = md.convert('mi-documento.pdf')
# Ver el contenido en Markdown
print(resultado.text_content)
# O guardarlo en un archivo
with open('mi-documento.md', 'w') as f:
 f.write(resultado.text_content)

Convertir una carpeta completa de PDFs automáticamente

from markitdown import MarkItDown
import os
md = MarkItDown()
carpeta = './mis-documentos'
for archivo in os.listdir(carpeta):
 if archivo.endswith('.pdf'):
 ruta = os.path.join(carpeta, archivo)
 resultado = md.convert(ruta)
 nombre_md = archivo.replace('.pdf', '.md')
 with open(os.path.join(carpeta, nombre_md), 'w') as f:
 f.write(resultado.text_content)
 print(f'Convertido: {archivo} -> {nombre_md}')

5. Integración MCP con Claude Desktop

Esta es la opción más poderosa. MarkItDown incluye un servidor MCP (Model Context Protocol) que, al conectarlo a Claude Desktop, convierte automáticamente cada archivo que subes — sin que tengas que ejecutar nada manualmente. Subes el archivo, Claude lo recibe en Markdown optimizado de forma transparente.

Paso 1 — Encuentra el archivo de configuración de Claude Desktop

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

Paso 2 — Agrega MarkItDown como servidor MCP

Abre el archivo de configuración con cualquier editor de texto y agrega lo siguiente dentro de la sección mcpServers:

{
 "mcpServers": {
 "markitdown": {
 "command": "python",
 "args": ["-m", "markitdown.mcp"]
 }
 }
}

Paso 3 — Reinicia Claude Desktop

Cierra completamente Claude Desktop y vuelve a abrirlo. En la interfaz verás el ícono de MarkItDown disponible como herramienta activa. A partir de ese momento, cada archivo que subas será convertido automáticamente a Markdown antes de ser procesado por Claude.

6. Problemas comunes y cómo resolverlos

Error: 'markitdown' no se reconoce como comando

Python no está en el PATH de tu sistema. Solución:

# Usa python -m en lugar del comando directo
python -m markitdown mi-archivo.pdf -o resultado.md

Error al instalar con pip install 'markitdown[all]'

Puede ser un problema de versión de Python o conflicto de dependencias. Solución:

# Crea un entorno virtual limpio primero
python -m venv venv-markitdown
# Actívalo (Mac/Linux)
source venv-markitdown/bin/activate
# Actívalo (Windows)
venv-markitdown\Scripts\activate
# Instala dentro del entorno
pip install 'markitdown[all]'

El archivo convertido tiene caracteres extraños

El PDF puede tener codificación no estándar. Solución:

# Especifica la codificación al guardar
markitdown mi-archivo.pdf -o resultado.md
# Luego abre resultado.md con tu editor y guarda como UTF-8

El MCP no aparece en Claude Desktop

Verifica que el JSON de configuración sea válido (sin comas extra, con comillas correctas). Puedes validarlo en jsonlint.com. Luego reinicia Claude Desktop completamente — en Mac, usa Cmd+Q, no solo cierres la ventana.

¿Quieres que implementemos MarkItDown dentro de un flujo de IA personalizado para tu negocio?

Podemos integrarlo con tus documentos existentes, tu base de conocimiento y los agentes de Claude para que toda tu operación consuma tokens de forma eficiente desde el primer día.

📲 Escríbenos directamente a nuestro agente de WhatsApp y agendamos una llamada.

Escríbenos por WhatsAppConoce Vianta AI