PDF en Claude Code: conversión, tokens y conservación de la estructura

¿Qué ocurre con un PDF en Claude y por qué cuesta entre 1.500 y 3.000 tokens por página?#

La documentación oficial de Anthropic describe el proceso en tres pasos sencillos:

Parece lógico, pero los costes de procesamiento aumentan de forma lineal con el número de páginas. Y esta cifra explica por qué se agota tu límite de uso con un solo PDF:

Para hacerse una idea, Anthropic midió el mismo PDF de 3 páginas en Bedrock en dos modos. En modo de texto (Converse Document Chat), consumió unos 1.000 tokens. Con análisis visual (Claude PDF Chat), consumió unos 7.000. Incluir imágenes hace que el procesamiento sea 7 veces más caro.

Las capturas de pantalla de las páginas son aún peores. Una captura de pantalla de 1000×1000 píxeles cuesta unos 1.300 tokens.

El mecanismo es sencillo: los PDF son caros porque Claude no confía en su OCR. Usa tanto el texto como la imagen para compararlos, y pagas por ambas capas a la vez. Con documentos grandes puedes hacerlo de otra manera: guarda el archivo como Markdown en la carpeta de tu proyecto y dile a Claude: «Aquí hay un documento con información; distribúyela». Claude repartirá el contenido entre sus propios archivos y seguirá trabajando con el texto organizado, en vez de consumirlo todo de una vez.

¿Cuántos tokens consume un PDF en una tarea habitual?#

Estas son las cifras concretas (modelo Sonnet 4.x, entrada a 3 $ por millón de tokens):

Y eso es solo un ciclo de 4 solicitudes. Después entra en juego el almacenamiento en caché de prompts (TTL de 5 minutos por defecto, hasta 1 hora en un nivel ampliado y hasta un 90 % de descuento en llamadas repetidas dentro de ese intervalo); los ahorros se multiplican.

Cada vez que subes el mismo PDF a un chat nuevo, Claude vuelve a leerlo; la caché no se conserva entre chats.

Si conviertes ese PDF de 15 páginas a Markdown una vez y lo añades como .md en cada uno de cuatro chats nuevos, el ejemplo usa 15 × 300 × 4 = 18.000 tokens de entrada, frente a 135.000. Los 300 tokens por página convertida y 2.250 por página PDF son supuestos del cálculo, no constantes medidas para todos los PDF. Cuenta tu documento real y confirma la calidad de conversión antes de estimar el ahorro.

El ahorro es aún más significativo con una suscripción a Claude Pro. Un informe de 100 páginas puede consumir todo el límite de 5 horas. Tras convertirlo a Markdown, caben más de 10 documentos de ese tipo en el mismo presupuesto.

¿Cuáles son los límites de la API de Anthropic para PDF en 2026?#

La documentación de Anthropic enumera los límites al principio (actualizados al 31 de mayo de 2026):

Claude.ai (la aplicación web para consumidores) tiene límites distintos: un máximo de 500 MB por archivo y hasta 20 archivos en un chat. Sin embargo, el análisis visual solo funciona con PDF de hasta 100 páginas; por encima de ese límite, Claude ve solo el texto, sin gráficos ni diagramas.

Hay tres formas de enviar un PDF a través de la API:

1. Mediante URL - "source": {"type": "url", "url": "..."} - la opción más sencilla cuando el documento está en línea.
2. En Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - para archivos locales.
3. A través de la Files API - "source": {"type": "file", "file_id": "file_abc123"} - para solicitudes repetidas; requiere el encabezado beta anthropic-beta: files-api-2025-04-14.

La Files API es la principal forma de ahorrar cuando trabajas con el mismo PDF en distintos chats. Súbelo una vez, obtén un file_id y úsalo en todas las interacciones. Con cache_control: ephemeral, las llamadas repetidas cuestan el 10 % del precio habitual.

Anthropic también ofrece consejos oficiales para reducir el uso:

Método 1: ¿Cómo se configura MarkItDown en 5 minutos?#

MarkItDown es un proyecto oficial de Microsoft mantenido por el equipo AutoGen. En GitHub tiene 134 mil estrellas y 9,2 mil forks (a finales de mayo de 2026). Su propósito se explica directamente en el README:

Formatos compatibles:

• Documentos: PDF, DOCX, PPTX, XLSX
• Web: HTML, JSON, XML, CSV
• Medios: audio con transcripción, imágenes con EXIF y OCR, vídeos de YouTube (mediante subtítulos)
• Archivos: ZIP, EPub
• Otros: todos los adjuntos de archivos Outlook MSG

Instalación

Requisito: Python 3.10+ (normalmente ya está instalado en macOS; en Windows tendrás que instalarlo por separado).

pip install 'markitdown[all]'

Si no necesitas todos los formatos, puedes instalar solo algunos:

pip install 'markitdown[pdf, docx, pptx]'

Convertir un solo archivo

El caso más sencillo:

markitdown document.pdf > document.md

Después, document.md aparecerá en la carpeta actual. Añádelo a Claude Code con @document.md o simplemente colócalo junto a tu proyecto.

API de Python

Si quieres integrarlo en tu script:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# You can save it straight away:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Lo que MarkItDown NO puede hacer

• OCR de PDF escaneados - no devuelve nada. Para escaneos, necesitas PyMuPDF4LLM o Docling.
• Diseños complejos con varias columnas - puede desordenar el orden de lectura.
• URL incrustadas en PDF - no las conserva.

Para los PDF sencillos (informes, artículos, documentación), MarkItDown es la mejor opción: una herramienta versátil que se instala en un minuto y no requiere conocimientos de Python. Las mediciones de su rendimiento con documentos en cirílico y escaneos se muestran en el análisis sobre cómo convertir un PDF a texto para IA.

Método 2: ¿Qué ofrece PyMuPDF4LLM y cuándo es mejor?#

MarkItDown ofrece variedad de formatos; PyMuPDF4LLM ofrece un procesamiento más profundo de PDF.

La versión vigente al 31 de mayo de 2026 es la 1.27.2.3 (publicada el 24 de abril de 2026).

Qué incluye

• Páginas con varias columnas y el orden de lectura correcto
• Conversión de tablas a Markdown con formato de GitHub
• Eliminación automática de encabezados y pies de página
• Extracción de imágenes con enlaces relativos a una carpeta aparte
• OCR inteligente: solo se aplica a las zonas ilegibles y ahorra aproximadamente un 50 % del tiempo de procesamiento
• Motor nativo C, no necesita GPU

Instalación

pip install pymupdf4llm

Uso

import pymupdf4llm

# Uso básico - directamente a Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Guardarlo:
with open("document.md", "w") as f:
    f.write(md_text)

En una sola línea, como prometí:

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

Cuándo elegir PyMuPDF4LLM en lugar de MarkItDown

• Cuando el PDF contiene muchos enlaces que necesitas conservar (MarkItDown los pierde).
• Cuando el documento está escaneado y necesitas OCR.
• Cuando necesitas procesar rápidamente miles de archivos en local: el motor nativo C es más rápido que los wrappers de Python.
• Cuando necesitas extraer imágenes del PDF a una carpeta aparte para procesarlas después.

Detalle de la licencia (importante para empresas)

PyMuPDF4LLM tiene doble licencia: AGPL v3 O una licencia comercial de Artifex.

AGPL significa que: si usas la biblioteca en un SaaS público, debes publicar todo el código fuente de tu servicio bajo la misma AGPL. Para uso interno (tu script en tu portátil), no hay restricciones.

Para desarrollar un producto comercial sin revelar el código, compra una licencia a Artifex (artifex.com). Los precios no están publicados; solicítalos al equipo de ventas.

Si estás desarrollando un producto para clientes, comprueba la licencia desde el principio. MarkItDown (MIT) y Docling (MIT) son opciones más seguras para SaaS.

Método 3: conectar MarkItDown al agente de inteligencia artificial Claude Code mediante MCP#

El modo CLI de MarkItDown significa «Convierto los archivos manualmente por adelantado»; el servidor MCP significa «Claude Code decide cuándo convertirlos».

Instalación

Necesitas el gestor de paquetes uv. No hace falta instalar el servidor por separado; uv lo descarga la primera vez que se ejecuta.

Configuración en Claude Code

Un solo comando conecta el servidor a todos tus proyectos, con la versión fijada:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

La entrada markitdown debería indicar “Connected”. El primer inicio descarga unos setenta paquetes y puede tardar hasta un minuto; después, el servidor se inicia en uno o dos segundos.

Estas son las razones por las que el comando necesita las dos variables. ORT_DISABLE_TELEMETRY=1 desactiva las estadísticas que el motor onnxruntime del servidor envía a Microsoft de forma predeterminada en Mac y Linux. UV_PYTHON=3.12 ejecuta el servidor con Python 3.12, para el que hay paquetes precompilados disponibles en Windows, Linux y Mac con Apple Silicon. En los Mac Intel y en macOS 13 y versiones anteriores, el servidor no se instala con Python 3.14. Hay una salvedad para Intel y la versión 3.12: uv compilará la biblioteca cryptography desde el código fuente porque no hay paquetes precompilados para Intel desde junio de 2026. La instalación tarda más y puede fallar. Si no tienes Python 3.12, uv lo descargará.

El servidor se ejecuta directamente en tu ordenador y puede abrir cualquier archivo al que tengas acceso. Si Claude Code estaba abierto, reinícialo y markitdown aparecerá en la lista de servidores MCP.

Cómo usarlo

En Claude Code, solo tienes que decir:

Convierte /Users/your-user/Documents/report.pdf a Markdown y analiza los puntos principales.

Claude llama por su cuenta a convert_to_markdown(uri), recibe el Markdown y trabaja con él; el PDF no se carga en el contexto.

URI compatibles

• file:// - archivos locales
• http://, https:// - documentos en línea
• data: - datos insertados (Base64)

Seguridad

Según el README oficial:

De forma predeterminada, está enlazado a localhost. Si lo ejecutas mediante HTTP/SSE (opción --http --host 127.0.0.1 --port 3001), no expongas el puerto al exterior sin un proxy inverso autenticado.

¿Qué método deberías elegir para tu tarea?#

Tabla comparativa ampliada:

Marker publica cifras de precisión impresionantes en pruebas de referencia:

Sin embargo, Marker necesita una GPU para alcanzar una buena velocidad y utiliza modelos de aprendizaje automático. Para la mayoría de las tareas con PDF de texto normal, PyMuPDF4LLM o MarkItDown bastan y funcionan en segundos sin GPU.

Una regla sencilla para elegir

1. Uno o dos PDF, necesitas rapidez - MarkItDown CLI.
2. Decenas de PDF, necesitas automatización - servidor MCP de MarkItDown o PyMuPDF4LLM en un script.
3. PDF con enlaces e imágenes donde importa conservar la estructura - PyMuPDF4LLM.
4. RAG en producción para empresas donde importa la estabilidad de las tablas - Docling.
5. Artículos científicos con fórmulas - Marker.
6. No quieres preocuparte por ello y prefieres dejar que Claude convierta los archivos - servidor MCP de MarkItDown.

¿Cómo se escribe un script listo para usar que convierta automáticamente una carpeta de documentos?#

Un ejemplo práctico: imagina que tienes 40 informes PDF y PPTX de clientes en una carpeta: extractos de cuentas de corretaje, contratos y presentaciones. Subir toda la carpeta a Claude directamente no sirve de nada: la ventana de contexto se llenará antes de la primera respuesta. Procesa toda la carpeta de una vez con el script de abajo y luego trabaja con archivos .md ligeros en lugar de PDF voluminosos.

Guarda este script como scripts/docs-to-md.sh en la raíz del proyecto:

#!/bin/bash
# docs-to-md.sh - convierte todos los documentos de una carpeta a Markdown con MarkItDown
# Uso: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Scanning $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

Dale permisos de ejecución:

chmod +x scripts/docs-to-md.sh

Ejecútalo:

bash scripts/docs-to-md.sh ./reports

Al terminar, ./reports/_md/ contendrá las versiones .md de todos los documentos. Añádelas a Claude Code con @reports/_md/ y trabaja con el texto comprimido en lugar de con PDF.

El script omite automáticamente los archivos ya convertidos (si el archivo .md es más reciente que el original); volver a ejecutarlo es rápido y no recalcula todo.

Idempotencia y conversión incremental

Si quieres que el script detecte los PDF modificados y guardados con el mismo nombre, añade una comprobación del hash del contenido:

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

Esta versión vuelve a convertir un archivo solo si su contenido ha cambiado.

¿Cuándo sigue siendo mejor usar un PDF en Claude que Markdown?#

Tres casos en los que la conversión a Markdown se queda corta:

1. Análisis visual de diagramas y gráficos

Si Claude necesita «leer» un gráfico —una curva de precios, un diagrama de procesos o un esquema de arquitectura—, esa información no aparece en Markdown. Markdown conserva solo los pies de figura; la figura en sí se pierde.

Solución: sube el PDF y activa explícitamente el modo visual. En la API de Claude, la opción funciona automáticamente; en AWS Bedrock necesitas la opción citations.

2. Tablas complejas con celdas combinadas

Las tablas Markdown son planas. Si el PDF contiene una tabla con celdas combinadas, encabezados de varios niveles o tablas anidadas, el convertidor la aplanará o perderá las relaciones entre sus elementos.

Solución: usa directamente el PDF, usa Docling (que gestiona mejor las tablas complejas) o dale formato manualmente tras la conversión.

3. Documentos como piezas con referencias a páginas

En documentos legales, contratos y actas, importa poder citar «página 7, párrafo 3». En Markdown se pierden los números de página.

Solución: PDF + Files API + almacenamiento en caché de prompts. Sube el documento una vez y luego haz referencia a él mediante file_id; Claude ve la paginación y puede citar páginas concretas.

Documentos breves

Si un PDF tiene menos de 2 páginas y lo usas una sola vez, no vale la pena convertirlo. 5.000 tokens para un PDF frente a 800 para Markdown no supone un ahorro suficiente como para justificar la instalación de MarkItDown.

El punto de equilibrio está en torno a 5 páginas o más, o 2 usos o más del mismo documento. Por debajo de eso, sube el PDF directamente; por encima, conviértelo.

¿Cuáles son los 5 errores más comunes que se cometen con los PDF en Claude?#

1. Subir el mismo PDF a un chat nuevo cada vez

Claude Pro tiene un límite de mensajes por cada periodo de 5 horas; un solo informe de 50 páginas puede agotarlo antes de que hagas una segunda pregunta.

Hay un principio sencillo para evitarlo: una tarea, un chat. Cuando la IA empieza a consumir una cantidad absurda de tokens, significa que estás metiendo todo en un solo chat y añadiendo el PDF una y otra vez. Dedica cada ventana a una microtarea. Convierte el documento a Markdown una vez y luego añade el archivo .md a cada ventana nueva junto con el proyecto. El círculo de la ventana de contexto no se pondrá amarillo.

Solución: conviértelo a Markdown una vez o usa la Files API con file_id y almacenamiento en caché de prompts.

2. Una captura de pantalla en vez de texto

Un ejemplo habitual: alguien quiere mostrarle a Claude un fragmento de código o una tabla, hace una captura de toda la pantalla de 1920×1080 y se pregunta por qué se le agota el límite tras 5 solicitudes.

Una captura de pantalla de 1000×1000 píxeles cuesta unos 1.300 tokens. El mismo texto copiado a mano cuesta entre 50 y 100 tokens. La diferencia es de 13 a 26 veces.

Solución: recorta las capturas para dejar solo la parte importante o, mejor aún, copia el texto directamente.

3. Un PDF escaneado sin OCR

MarkItDown no puede hacer OCR. Si conviertes un escaneo, obtendrás un archivo .md vacío (o 3 líneas de texto ilegible).

Solución: para documentos escaneados, usa PyMuPDF4LLM (con su OCR inteligente integrada) o Docling.

4. Ignorar el límite de 100 páginas

La documentación de Anthropic establece un límite de 600 páginas por solicitud, pero, en la práctica, el límite para los modelos con contexto de 200K (Sonnet 4.x, Opus 4.x) es de 100 páginas. El límite de 600 páginas está pensado para modelos antiguos o niveles especiales.

Si subes un informe de 150 páginas a Sonnet 4.6, recibirás un error o, peor aún, Claude procesará solo las primeras 100 páginas y actuará como si hubiera leído el documento entero.

Solución: divide los PDF largos en partes antes de subirlos. O conviértelos a Markdown: no hay límite de páginas, solo de tokens.

5. No usar el almacenamiento en caché de prompts para solicitudes repetidas

Si trabajas con el mismo documento mediante la API, inclúyelo en cache_control: ephemeral. Las solicitudes repetidas en un plazo de 5 minutos cuestan el 10 % del precio inicial. Una solicitud cuesta más; las demás tienen un descuento del 90 %.

Solución: activa por defecto el almacenamiento en caché de prompts para cualquier documento que subas más de una vez.

Qué sigue: ingeniería de contexto#

Convertir PDF a Markdown es una manera de ahorrar tokens. Por sí solo, no hace que las respuestas de Claude sean más precisas. La precisión proviene de la ingeniería de contexto: la disciplina de decidir qué incluir en el contexto del modelo antes de hacer una pregunta.

Si tu CLAUDE.md tiene 800 líneas, tu proyecto cuenta con 10 servidores MCP innecesarios y añades un PDF de 100 páginas, la conversión a Markdown evitará una fuga, pero las otras tres seguirán ahí. Por eso estas guías tratan lo siguiente:

• Adónde van los tokens en Claude Code - 9 patrones de pérdida de contexto, no solo con los PDF.
• Ingeniería de contexto en 2026 - la gestión sistemática del contexto.
• Modo Plan en Claude Code - el modo de planificación antes de que Claude empiece a escribir código.