PDF in Claude Code: conversione, token e conservazione della struttura

Cosa succede a un PDF in Claude e perché ogni pagina costa 1.500–3.000 token?#

La documentazione ufficiale di Anthropic descrive il processo in tre semplici passaggi:

Sembra logico, ma i costi di elaborazione crescono linearmente con il numero di pagine. Ecco il dato che spiega perché il limite del tuo abbonamento si esaurisce con un solo PDF:

Per capire quanto sia, Anthropic ha misurato lo stesso PDF di 3 pagine su Bedrock in due modalità. In modalità testo (Converse Document Chat) ha usato ~1.000 token. Con l’analisi visiva (Claude PDF Chat) ne ha usati ~7.000. L’inclusione delle immagini rende l’elaborazione 7 volte più costosa.

Le schermate delle pagine sono ancora peggio. Una schermata da 1000×1000 pixel costa circa 1.300 token.

Il meccanismo è semplice: i PDF sono costosi perché Claude non si fida del suo OCR. Usa sia il testo sia l’immagine per poterli confrontare, e tu paghi entrambi i livelli in una volta. Per i documenti lunghi puoi fare diversamente: salva il file come Markdown nella cartella del progetto e dì a Claude: «ecco un documento con delle informazioni: distribuiscile». Claude distribuirà il contenuto nei propri file e continuerà a lavorare sul testo organizzato, invece di consumare tutto in una volta.

Quanto consuma un PDF in un’attività tipica?#

I numeri specifici (modello Sonnet 4.x, input a $3 per milione di token):

E questo vale per un solo ciclo di 4 richieste. In seguito entra in gioco la cache dei prompt (TTL predefinito di 5 minuti, fino a 1 ora nel livello esteso, con uno sconto fino al 90% sulle chiamate ripetute nella finestra): il risparmio si moltiplica.

Ogni volta che carichi lo stesso PDF in una nuova chat, Claude lo legge di nuovo; la cache non viene mantenuta tra una chat e l’altra.

Se converti una volta lo stesso PDF di 15 pagine in Markdown e lo aggiungi come .md a ciascuna di quattro nuove chat, l’esempio usa 15 × 300 × 4 = 18,000 token di input anziché 135,000. I 300 token per pagina convertita e 2,250 per pagina PDF sono ipotesi del calcolo, non costanti misurate per ogni documento. Conta il tuo file e verifica la qualità prima di stimare il risparmio.

Il calcolo diventa ancora più significativo con un abbonamento Claude Pro. Un report di 100 pagine può consumare l’intero limite di 5 ore. Dopo la conversione in Markdown, nello stesso budget ci stanno più di 10 documenti di questo tipo.

Quali sono i limiti dell’API Anthropic per i PDF nel 2026?#

La documentazione di Anthropic elenca i limiti all’inizio (aggiornata al 31 maggio 2026):

Claude.ai (l’app web per i consumatori) ha limiti diversi: massimo 500 MB per file e fino a 20 file in una chat. L’analisi visiva funziona però solo per i PDF fino a 100 pagine: oltre tale limite Claude vede solo il testo, senza grafici e diagrammi.

Tre modi per inviare un PDF tramite API:

1. Tramite URL - "source": {"type": "url", "url": "..."} - il più semplice quando il documento è online.
2. In Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - per i file locali.
3. Tramite Files API - "source": {"type": "file", "file_id": "file_abc123"} - per richieste ripetute; richiede l’header beta anthropic-beta: files-api-2025-04-14.

Files API è il metodo principale per risparmiare quando lavori con lo stesso PDF in chat diverse. Caricalo una volta, ottieni un file_id e usalo per tutte le interazioni. Con cache_control: ephemeral, le chiamate ripetute costano il 10% del prezzo normale.

Anthropic fornisce anche consigli ufficiali per ridurre l’uso:

Metodo 1: come configurare MarkItDown in 5 minuti?#

MarkItDown è un progetto ufficiale Microsoft gestito dal team AutoGen. Su GitHub ha 134 mila stelle e 9,2 mila fork (alla fine di maggio 2026). Il suo scopo è descritto direttamente nel README:

Formati supportati:

• Documenti: PDF, DOCX, PPTX, XLSX
• Web: HTML, JSON, XML, CSV
• Media: audio con trascrizione, immagini con EXIF e OCR, video di YouTube (tramite sottotitoli)
• Archivi: ZIP, EPub
• Altro: tutti gli allegati contenuti nei file Outlook MSG

Installazione

Requisito: Python 3.10+ (di solito è già installato su macOS; su Windows devi installarlo separatamente).

pip install 'markitdown[all]'

Se non ti servono tutti i formati, puoi installare solo quelli che ti interessano:

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

Conversione di un singolo file

Il caso più semplice:

markitdown document.pdf > document.md

A quel punto, document.md apparirà nella cartella corrente. Aggiungilo a Claude Code con @document.md oppure mettilo accanto al progetto.

API Python

Se vuoi integrarlo nel tuo script:

from markitdown import MarkItDown

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

# Puoi salvarlo direttamente:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Cosa NON può fare MarkItDown

• OCR per PDF scansionati - non restituisce nulla. Per le scansioni servono PyMuPDF4LLM o Docling.
• Layout complessi a più colonne - può confondere l’ordine di lettura.
• URL incorporati nei PDF - non li conserva.

Per i PDF semplici (report, articoli, documentazione), MarkItDown è la scelta migliore: uno strumento versatile che si installa in un minuto e non richiede conoscenze di Python. Le sue prestazioni con documenti contenenti testo cirillico e scansioni sono illustrate nelle misurazioni dell’analisi su come convertire un PDF in testo per l’AI.

Metodo 2: cosa offre PyMuPDF4LLM e quando è la scelta migliore?#

MarkItDown offre ampiezza di formati; PyMuPDF4LLM offre profondità nell’elaborazione dei PDF.

La versione al 31 maggio 2026 è la 1.27.2.3 (rilasciata il 24 aprile 2026).

Contenuto

• Pagine a più colonne con il corretto ordine di lettura
• Tabelle convertite in Markdown compatibile con GitHub
• Intestazioni e piè di pagina rimossi automaticamente
• Immagini estratte con link relativi in una cartella separata
• OCR intelligente: applicato solo alle aree illeggibili, fa risparmiare ~50% del tempo di elaborazione
• Motore C nativo, non serve una GPU

Installazione

pip install pymupdf4llm

Utilizzo

import pymupdf4llm

# Uso di base - direttamente in Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

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

In una riga, come promesso:

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

Quando scegliere PyMuPDF4LLM invece di MarkItDown

• Quando il PDF contiene molti link che vuoi conservare (MarkItDown li perde).
• Quando il documento è scansionato e ti serve l’OCR.
• Quando ti serve velocità su migliaia di file in locale: il motore C nativo è più veloce dei wrapper Python.
• Quando ti servono le immagini del PDF in una cartella separata per elaborarle ulteriormente.

Dettagli sulla licenza (importante per le aziende)

PyMuPDF4LLM è distribuito con doppia licenza: AGPL v3 OPPURE commerciale Artifex.

AGPL significa: se usi la libreria in un SaaS pubblico, devi pubblicare tutto il codice sorgente del servizio con la stessa licenza AGPL. Per uso interno (il tuo script sul tuo portatile), non ci sono restrizioni.

Per lo sviluppo commerciale senza divulgare il codice, acquista una licenza da Artifex (artifex.com). I prezzi non sono pubblicati: richiedili all’ufficio vendite.

Se stai creando un prodotto per i clienti, verifica la licenza fin dall’inizio. MarkItDown (MIT) e Docling (MIT) sono scelte più sicure per il SaaS.

Metodo 3: come collegare MarkItDown all’agente AI Claude Code tramite MCP?#

MarkItDown in modalità CLI significa «converto i file manualmente in anticipo»; il server MCP significa «Claude Code decide quando convertire».

Installazione

Ti serve il gestore di pacchetti uv. Non è necessario installare il server separatamente: uv lo scarica al primo avvio.

Configurazione in Claude Code

Un comando collega il server a tutti i tuoi progetti, con la versione bloccata:

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 voce markitdown dovrebbe indicare «Connected». Il primo avvio scarica circa settanta pacchetti e richiede fino a un minuto; in seguito, il server si avvia in uno o due secondi.

Ecco perché il comando richiede le due variabili. ORT_DISABLE_TELEMETRY=1 disabilita le statistiche che il motore onnxruntime integrato nel server invia per impostazione predefinita a Microsoft su Mac e Linux. UV_PYTHON=3.12 avvia il server con Python 3.12, per cui sono disponibili pacchetti precompilati su Windows, Linux e Mac con Apple Silicon. Sui Mac Intel e su macOS 13 e versioni precedenti, il server non si installa con Python 3.14. C’è una precisazione per Intel e 3.12: uv compilerà la libreria cryptography dai sorgenti, perché dal giugno 2026 non è disponibile un pacchetto Intel precompilato. L’installazione richiede più tempo e può non riuscire. Se non hai Python 3.12, uv lo scaricherà per te.

Il server viene eseguito direttamente sul tuo computer e può aprire qualsiasi file a cui hai accesso. Se Claude Code era aperto, riavvialo: markitdown apparirà nell’elenco dei server MCP.

Come usarlo

In Claude Code, basta dire:

Converti /Users/your-user/Documents/report.pdf in Markdown e analizza i punti principali.

Claude chiama direttamente convert_to_markdown(uri), riceve il Markdown e ci lavora: il PDF non viene caricato nel contesto.

URI supportati

• file:// - file locali
• http://, https:// - documenti online
• data: - dati in linea (Base64)

Sicurezza

Dal README ufficiale:

Per impostazione predefinita, si associa a localhost. Se lo esegui tramite HTTP/SSE (opzione --http --host 127.0.0.1 --port 3001), non esporre la porta all’esterno senza un reverse proxy autenticato.

Quale metodo scegliere per la tua attività?#

Tabella comparativa estesa:

Marker pubblica risultati di accuratezza impressionanti nei benchmark:

Marker però richiede una GPU per raggiungere una buona velocità e include modelli di machine learning. Per la maggior parte delle attività (normali PDF testuali), PyMuPDF4LLM o MarkItDown svolgono il lavoro in pochi secondi senza GPU.

Una semplice regola per scegliere

1. Uno o due PDF, serve rapidità - MarkItDown CLI.
2. Decine di PDF, serve automazione - server MarkItDown MCP o PyMuPDF4LLM in uno script.
3. PDF con link e immagini di cui è importante conservare la struttura - PyMuPDF4LLM.
4. RAG in produzione per le aziende, dove è importante la stabilità delle tabelle - Docling.
5. Articoli scientifici con formule - Marker.
6. Non vuoi pensarci: lascia che Claude converta i file - server MarkItDown MCP.

Come scrivere uno script pronto all’uso per convertire automaticamente una cartella di documenti?#

Un esempio pratico: immagina di avere 40 report PDF e PPTX di clienti in una cartella: estratti conto di brokeraggio, contratti, presentazioni. Caricare direttamente la cartella in Claude è inutile: la finestra di contesto si riempirà di informazioni prima della prima risposta. Fai passare l’intera cartella nello script qui sotto in un solo passaggio, poi continua a lavorare con file .md leggeri invece che con PDF pesanti.

Salva questo script come scripts/docs-to-md.sh nella radice del progetto:

#!/bin/bash
# docs-to-md.sh - converte tutti i documenti in una cartella in Markdown usando 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"

Rendilo eseguibile:

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

Eseguilo:

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

Dopo l’esecuzione, ./reports/_md/ contiene le versioni .md di tutti i documenti. Aggiungile a Claude Code con @reports/_md/ e lavora sul testo compresso invece che sui PDF.

Lo script salta automaticamente i file già convertiti (se il file .md è più recente della fonte): rieseguirlo è rapido e non ricalcola tutto.

Idempotenza e conversione incrementale

Se vuoi che lo script rilevi i PDF modificati (risalvati con lo stesso nome), aggiungi un controllo dell’hash del contenuto:

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"

Questa versione riconverte un file solo se il suo contenuto è cambiato.

Quando è ancora meglio usare un PDF in Claude invece di Markdown?#

Tre casi in cui la conversione in Markdown non basta:

1. Analisi visiva di diagrammi e grafici

Se Claude deve «leggere» un grafico — una curva dei prezzi, un diagramma di processo o uno schema architettonico — quell’informazione non è presente in Markdown. Markdown conserva solo le didascalie delle figure; la figura stessa va persa.

Soluzione: carica il PDF e attiva esplicitamente la modalità visiva. Nell’API Claude il flag funziona automaticamente; su AWS Bedrock serve il flag citations.

2. Tabelle complesse con celle unite

Le tabelle Markdown sono piatte. Se il PDF contiene una tabella con celle unite, intestazioni multilivello o tabelle nidificate, il convertitore appiattirà la struttura o perderà le relazioni.

Soluzione: usa direttamente il PDF, usa Docling (gestisce al meglio le tabelle complesse) oppure formatta manualmente il risultato dopo la conversione.

3. Documenti come artefatti con riferimenti alle pagine

Per documenti legali, contratti e verbali è importante poter citare «pagina 7, paragrafo 3». In Markdown i numeri di pagina vanno persi.

Soluzione: PDF + Files API + cache dei prompt. Caricalo una volta, poi fai riferimento al file tramite file_id: Claude vede la paginazione e può citare pagine specifiche.

Documenti brevi

Se un PDF ha meno di 2 pagine e lo usi una sola volta, convertirlo non conviene. 5.000 token per un PDF contro 800 per Markdown non rappresentano un risparmio sufficiente a giustificare l’installazione di MarkItDown.

Il punto di pareggio è circa 5+ pagine o 2+ usi dello stesso documento. Al di sotto, carica direttamente il PDF; al di sopra, convertilo.

Quali sono i 5 errori più comuni che si commettono con i PDF in Claude?#

1. Caricare lo stesso PDF ogni volta in una nuova chat

Claude Pro ha un limite ai messaggi nell’arco di 5 ore: un report di 50 pagine può consumarlo tutto prima che tu faccia una seconda domanda.

Il principio è semplice: un’attività, una chat. Quando l’AI inizia a consumare una quantità assurda di token, significa che stai stipando tutto in una chat e aggiungendo il PDF più e più volte. Dedica una micro-attività a ogni finestra. Converti il documento in Markdown una sola volta, poi aggiungi il file .md a ogni nuova finestra insieme al progetto. Il cerchio della finestra di contesto non diventerà giallo.

Soluzione: convertilo una volta in Markdown oppure usa Files API con file_id e cache dei prompt.

2. Una schermata invece del testo

Un esempio tipico: qualcuno vuole mostrare a Claude un pezzo di codice o una tabella, fa una schermata dell’intero schermo da 1920×1080 e si chiede perché il limite si sia esaurito dopo 5 richieste.

Una schermata da 1000×1000 pixel costa ~1.300 token. Lo stesso testo copiato a mano ne costa 50–100. La differenza è da 13 a 26 volte.

Soluzione: ritaglia con precisione le schermate (solo la parte importante) oppure, meglio ancora, copia direttamente il testo.

3. Un PDF scansionato senza OCR

MarkItDown non può eseguire l’OCR. Se converti una scansione, il risultato è un file .md vuoto (o con 3 righe di rumore).

Soluzione: per le scansioni usa PyMuPDF4LLM (con OCR intelligente integrato) oppure Docling.

4. Ignorare il limite di 100 pagine

La documentazione di Anthropic indica un limite di 600 pagine per richiesta, ma in pratica il limite per i modelli con contesto da 200K (Sonnet 4.x, Opus 4.x) è di 100 pagine. Il limite di 600 pagine è destinato a modelli più vecchi o a livelli speciali.

Se carichi un report di 150 pagine su Sonnet 4.6, riceverai un errore o, peggio, Claude elaborerà solo le prime 100 pagine e agirà come se avesse letto l’intero documento.

Soluzione: suddividi i PDF lunghi in parti prima di caricarli. Oppure convertili in Markdown: non c’è un limite di pagine, solo un limite di token.

5. Non usare la cache dei prompt per le richieste ripetute

Se lavori con lo stesso documento tramite API, racchiudilo in cache_control: ephemeral. Le chiamate ripetute entro 5 minuti costano il 10% del prezzo iniziale. Una richiesta costa di più; le successive hanno uno sconto del 90%.

Soluzione: attiva la cache dei prompt per impostazione predefinita per tutto ciò che carichi più di una volta.

E adesso: ingegneria del contesto#

Convertire PDF in Markdown è un modo per risparmiare token. Da solo, non rende più accurate le risposte di Claude. L’accuratezza deriva dall’ingegneria del contesto, la disciplina che consiste nel decidere cosa inserire nel contesto del modello prima di porre una domanda.

Se il tuo CLAUDE.md ha 800 righe, il tuo progetto ha 10 server MCP superflui e aggiungi un PDF di 100 pagine, la conversione in Markdown eviterà una perdita, ma le altre tre resteranno. Ecco perché queste guide trattano:

• Dove finiscono i token in Claude Code - 9 schemi di dispersione del contesto, non solo PDF.
• Ingegneria del contesto nel 2026 - la gestione sistematica del contesto.
• Modalità Plan in Claude Code - la modalità di pianificazione prima che Claude inizi a scrivere codice.