Arrête de donner tes PDF à Claude

Tu déposes un contrat de 20 pages dans Claude, tu poses une question, et la conversation est déjà à moitié pleine avant sa première réponse. Ce n'est pas un bug : un PDF entre deux fois dans le contexte. Ce guide t'explique le mécanisme, puis te donne le correctif complet : MarkItDown, l'outil open source de Microsoft, avec la config exacte à coller, format par format, et ce qu'il faut faire des PDF scannés.

1Ce qui se passe vraiment quand tu déposes un PDF

Ce n'est pas une théorie, c'est décrit noir sur blanc dans la documentation Anthropic. Quand un PDF arrive dans Claude, trois choses s'enchaînent :

• Chaque page est convertie en image. Une page = une image, du début à la fin du document.
• Le texte de chaque page est extrait à côté et fourni en plus de l'image de cette même page.
• Les deux partent ensemble dans le contexte. Le modèle analyse le texte ET l'image pour comprendre aussi les graphiques, schémas et mises en page.

C'est une bonne architecture. C'est même ce qui permet à Claude de lire un graphique dans un rapport annuel. Mais tu la paies sur tous tes documents, y compris ceux qui ne sont que du texte.

Le chiffrage

La doc annonce 1 500 à 3 000 tokens par page pour le texte seul, selon la densité. À cela s'ajoute le coût image de la page, calculé comme n'importe quelle image envoyée au modèle.

Concrètement : sur l'API ça se voit sur la facture, sur un abonnement ça se voit sur ton quota. Et surtout, la fenêtre de contexte se remplit deux fois plus vite. Claude « oublie » le début du document, et tu es bloqué en pleine journée. Source : documentation Anthropic, « PDF support ».

2Pourquoi le markdown, et pas « du texte »

Le markdown n'est pas un choix esthétique, c'est le format natif des modèles. Ils en produisent spontanément dans leurs réponses sans qu'on le leur demande : ils ont été massivement entraînés dessus.

Et il est d'une efficacité brutale. Un dièse et c'est un titre. Un pipe et c'est un tableau. Deux tirets et c'est une liste. La structure d'un document tient en quelques caractères, là où l'image de la page en coûtait des milliers, tout en gardant ce qui compte réellement : les titres, la hiérarchie, les tableaux, les liens.

3MarkItDown : ce que c'est exactement

github.com/microsoft/markitdown est un utilitaire Python de Microsoft (construit par l'équipe AutoGen), open source, sous licence MIT, avec plus de 177 000 étoiles sur GitHub. Tu lui donnes un fichier, il te rend du markdown.

Sa philosophie, écrite dans le README : il n'est pas conçu pour faire une conversion « belle pour un humain ». Il est conçu pour préserver la structure importante (titres, listes, tableaux, liens) à destination des LLM et des pipelines d'analyse de texte. C'est exactement notre besoin.

Ce qu'il sait ouvrir : PDF, Word, PowerPoint, Excel, HTML, formats texte (CSV, JSON, XML), EPub, images (métadonnées EXIF), audio (métadonnées + transcription), archives ZIP (il itère sur le contenu), et même une URL YouTube.

Prérequis : Python 3.10 ou plus. Deux façons de t'en servir avec Claude : le serveur MCP (Claude convertit tout seul) ou la ligne de commande (tu convertis avant). Les deux ci-dessous.

Récupérer le dépôt GitHub

Dans le cas le plus simple tu n'as rien à cloner : pip suffit (section 5). Tu as besoin du dépôt dans deux situations : installer depuis les sources, et construire l'image Docker que la config MCP de Claude Desktop appelle. Dans les deux cas, ça commence pareil :

git clone https://github.com/microsoft/markitdown.git
cd markitdown

Installer depuis les sources, en mode éditable, utile si tu veux lire le code d'un convertisseur ou l'adapter à un format maison :

pip install -e 'packages/markitdown[all]'

Construire l'image Docker du serveur MCP. Le sous-dossier du serveur contient son propre Dockerfile ; c'est cette image markitdown-mcp:latest que la configuration Claude Desktop de la section suivante va lancer :

cd packages/markitdown-mcp
docker build -t markitdown-mcp:latest .

4Le serveur MCP : Claude convertit tout seul

C'est la version que je recommande. Une fois branché, tu déposes ou tu pointes un fichier, et Claude appelle l'outil de conversion lui-même. Le package officiel s'appelle markitdown-mcp. Il expose un seul outil : convert_to_markdown(uri), où l'URI peut être http:, https:, file: ou data:.

pip install markitdown-mcp

Claude Desktop

Ouvre le fichier claude_desktop_config.json (Réglages → Développeur → Modifier la configuration) et ajoute l'entrée. Version directe, si markitdown-mcp est installé sur ta machine :

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

La version recommandée par le README officiel pour Claude Desktop passe par Docker. C'est plus propre, et surtout ça isole le serveur. Tu construis l'image une fois (voir la section 3, « Récupérer le dépôt GitHub »), puis :

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    }
  }
}

Dans un conteneur, Claude ne voit que ce que tu lui montes. Pour lui donner accès à un dossier de ta machine, ajoute un montage. Ici, /Users/toi/Documents devient /workdir côté conteneur :

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "/Users/toi/Documents:/workdir",
               "markitdown-mcp:latest"]
    }
  }
}

Un fichier rapport.pdf dans ce dossier sera alors adressable en file:///workdir/rapport.pdf. Redémarre Claude Desktop après modification : le serveur doit apparaître dans la liste des outils disponibles.

Claude Code

En une commande dans ton terminal :

claude mcp add markitdown -- markitdown-mcp

Ajoute -s user pour l'avoir dans tous tes projets plutôt que dans le projet courant. Si tu préfères le versionner avec ton équipe, crée un fichier .mcp.json à la racine du projet :

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

Vérifie ensuite avec claude mcp list, ou /mcp dans une session, que le serveur est bien connecté.

5L'installation locale, en ligne de commande

Utile si tu veux convertir par lots, garder les fichiers markdown, ou brancher la conversion dans une automatisation. Crée un environnement isolé, puis installe :

# environnement virtuel
python -m venv .venv
source .venv/bin/activate

# installation avec tous les formats
pip install 'markitdown[all]'

Si tu utilises uv : uv venv --python=3.12 .venv puis uv pip install 'markitdown[all]'.

markitdown contrat.pdf > contrat.md      # redirection
markitdown contrat.pdf -o contrat.md     # ou sortie explicite
cat contrat.pdf | markitdown             # ou en pipe

Tu n'as pas besoin de tout : les formats sont des options installables séparément. pip install 'markitdown[pdf, docx, pptx]' n'installe que ces trois-là.

6Ce qui passe bien, et ce qui passe mal

C'est la partie que personne ne te dit. Tous les formats ne se convertissent pas avec la même qualité. Voilà à quoi t'attendre, et le réflexe à avoir pour chacun.

7Les PDF scannés : là où MarkItDown s'arrête

Un PDF scanné, ce n'est pas du texte : c'est une photo de texte. MarkItDown n'embarque pas d'OCR par défaut : il te rend donc une page vide, sans erreur bruyante. C'est le piège classique.

Trois sorties possibles, de la plus simple à la plus industrielle :

1. Laisse ce PDF-là à Claude en direct. Contre-intuitif après tout ce guide, mais c'est le cas où la vision vaut son coût : Claude lit très bien une page scannée, puisqu'il la traite comme une image. Sur trois pages, c'est la meilleure décision. Sur trois cents, non.

2. Le plugin markitdown-ocr. Il ajoute la reconnaissance de texte aux convertisseurs PDF, Word, PowerPoint et Excel en s'appuyant sur un modèle de vision, sans dépendance lourde à installer :

pip install markitdown-ocr

Il faut lui fournir un client de modèle de vision (les plugins s'activent avec --use-plugins en ligne de commande, ou enable_plugins=True côté Python). Sans client fourni, l'OCR est silencieusement ignoré, d'où l'importance de vérifier la sortie.

3. Les services Azure, pour du volume. Le dépôt intègre Azure Document Intelligence ([az-doc-intel]) et Azure Content Understanding ([az-content-understanding]), pensés pour l'extraction de qualité sur des scans, des tableaux complexes et des documents longs :

markitdown scan.pdf --use-cu --cu-endpoint "<ton_endpoint>"

C'est du cloud facturé à l'appel : réservé aux volumes où le temps gagné dépasse largement le coût. Pour un scan ponctuel, l'option 1 suffit.

8Le protocole complet, en une page

La règle est simple : tu ne donnes une image à un modèle que quand tu as réellement besoin de ses yeux. Voilà la décision, dans l'ordre.

Trois actions pour aujourd'hui : (1) installe le serveur MCP (5 minutes), (2) reprends ton dernier gros PDF et convertis-le pour voir la différence, (3) fais du .md ton format de dépôt par défaut. Le reste suit tout seul.