Aller au contenu principal
PPDF123

Serveurs MCP PDF123 pour agents IA

MCP, le Model Context Protocol, est un standard ouvert qui permet à des clients IA comme Claude Code, Claude Desktop et Cursor d'appeler des outils externes. PDF123 propose un serveur MCP local, @pdf123/mcp, pour les fichiers de votre machine, et un point de terminaison hébergé qui utilise une clé d'API.

@pdf123/mcpNode 20.3 ou version ultérieure

Installation

npx -y @pdf123/mcp
Sur cette page

Quel serveur MCP choisir ?

Les deux serveurs exposent les opérations de PDF123. Ils diffèrent par l'endroit où ils s'exécutent et par la manière dont les fichiers leur parviennent.

Local : @pdf123/mcpHébergé : /mcp
S'exécuteSur votre machine, lancé par le client MCP via stdioSur les serveurs PDF123, à https://pdf123.xyz/mcp
EntréeChemins de fichiers sur le disque. Le serveur les envoie et enregistre le résultat à côté du fichier d'entréeFichiers transmis par l'outil d'envoi
IdentifiantsAucun en usage anonyme. PDFX_API_KEY est facultativeEn-tête X-API-KEY à chaque requête. Sans lui, la réponse est 401
Installationnpx -y @pdf123/mcpAucune. Ajoutez l'URL et l'en-tête au client
OutilsCinq outils pour tout le catalogue de 97 outilsSept outils : describe, convert, pages, misc, security, upload et download
À utiliser quandUn agent travaille sur des documents d'un dossier localUn agent ou un service hébergé gère déjà les envois via l'API

Utilisez le serveur local pour les assistants de code sur un ordinateur portable. Utilisez le point de terminaison hébergé quand l'agent s'exécute dans le cloud et ne peut pas lire votre disque.

Comment installer le serveur MCP local ?

Rien n'est à installer, car le client MCP lance le serveur avec npx. Dans Claude Code, ajoutez-le avec une seule commande.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop lit claude_desktop_config.json et Cursor lit .cursor/mcp.json. Les autres clients ont une page ou un fichier de réglages MCP. Tous acceptent la même entrée mcpServers.

Configuration du client MCPjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Redémarrez le client après avoir modifié sa configuration. Pour garder une copie dans votre PATH, lancez npm install -g @pdf123/mcp, qui fournit la commande pdf123-mcp. Le serveur exige Node 20.3 ou plus récent et une base d'API joignable. Il n'existe pas de mode hors ligne.

Que demander en premier à l'agent ?

Demandez en langage courant et nommez les fichiers. Par exemple :

Fusionne ~/Documents/a.pdf et ~/Documents/b.pdf, puis compresse le résultat.

L'agent appelle pdf123_run_pipeline, ou pdf123_run_tool deux fois, envoie les fichiers à PDF123 et répond avec le chemin du fichier enregistré. Le résultat est enregistré à côté de la première entrée et ne remplace jamais un fichier existant. Les mêmes opérations existent sous les noms Fusionner et Compresser sur le site.

Quels outils le serveur local propose-t-il ?

Le serveur a cinq outils. Les identifiants d'outils comme merge sont de simples arguments de type chaîne, ce qui garde la liste d'outils courte.

OutilFonctionArguments principaux
pdf123_list_toolsListe les outils, une ligne chacungroup, query, format
pdf123_describe_toolAffiche les champs d'un outil, ses valeurs par défaut, ses valeurs autorisées et s'il fonctionne par lotstool
pdf123_run_toolLance un outil sur des fichiers locaux et renvoie le chemin enregistré ou le rapport JSONtool, files, params, output
pdf123_run_pipelineEnchaîne jusqu'à 8 outils en une seule requêtesteps, files, output
pdf123_callEnvoie une requête brute à n'importe quel identifiant d'outil, d'opération ou chemin /api/...target, files, fields

Un agent appelle généralement pdf123_list_tools pour trouver un outil, pdf123_describe_tool pour lire ses champs, puis pdf123_run_tool. Un identifiant mal saisi renvoie des suggestions « vouliez-vous dire ».

Comment fonctionnent les lots, les mots de passe et les pipelines ?

  • Lots. Plusieurs fichiers donnés à un outil à fichier unique s'exécutent en lot, avec un résultat par fichier. Chaque fichier est enregistré dès qu'il est terminé. La réponse est un rapport par fichier. Si un fichier échoue, la réponse est une erreur accompagnée du rapport, de sorte que l'agent puisse relancer uniquement les fichiers en échec.
  • Mots de passe. input_password ouvre toutes les entrées chiffrées. passwords définit un mot de passe par fichier, dans le même ordre que files, avec une chaîne vide pour un fichier ouvert. Cela fonctionne aussi pour les outils multifichiers comme Fusionner.
  • Pipelines. pdf123_run_pipeline accepte jusqu'à 8 étapes, chacune alimentant la suivante. Il accepte les mêmes arguments de mot de passe.
  • Appels bruts. pdf123_call atteint les opérations plus récentes que le serveur. Rien n'est validé en local.
  • Outils de filtre. Un outil dont l'identifiant commence par filter- répond {"matched": false} quand sa condition n'est pas remplie. C'est un résultat, pas une erreur.
  • Nouvelles tentatives. idempotencyKey rejoue le premier résultat pendant 24 heures.

Comment limiter les dossiers accessibles à l'agent ?

Définissez PDFX_MCP_ROOT sur un répertoire. Séparez plusieurs répertoires par un deux-points, ou par un point-virgule sous Windows. Le serveur ne lit alors les entrées et n'écrit les résultats que dans ces répertoires. Les chemins extérieurs, les échappements par .. et les liens symboliques qui sortent de ces répertoires sont refusés avant tout envoi, avec Code: path_not_allowed. Sans cette variable, tout chemin que le processus du serveur peut atteindre est autorisé.

Restreindre l'accès aux fichiersjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Définissez les variables d'environnement dans le bloc env du client, ou avec claude mcp add -e NAME=value. PDFX_API_BASE oriente plutôt le serveur vers votre propre pdfx-server ; voir Auto-hébergement.

À quoi ressemblent les résultats et les erreurs ?

Un résultat unique est un petit objet JSON avec le path enregistré, le contentType et la taille en bytes. Le résultat d'un lot contient processed, unmatched, failed et une liste files. Ces formats correspondent à pdfx --json dans la ligne de commande. Un outil qui renvoie un rapport, comme Infos du document, renvoie ce rapport directement dans la réponse.

Résultat uniquejson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Un appel en échec revient sous forme d'erreur d'outil. Son texte se termine par des lignes Reason:, Code: et Hint: quand le serveur les a fournies, afin qu'un agent puisse se brancher sur le code.

Texte d'erreurtext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

Si un identifiant d'outil contient une faute de frappe, l'erreur liste des identifiants proches et se termine par Code: unknown_tool. Un outil qui n'a rien à renvoyer, comme pdf-to-csv sur un PDF sans tableau, renvoie Code: no_content au lieu d'un fichier vide. Voir Codes d'erreur.

Comment utiliser le point de terminaison MCP hébergé ?

L'API intègre un serveur MCP à POST https://pdf123.xyz/mcp. Authentifiez-vous avec le même en-tête X-API-KEY que celui de l'API REST. Sans clé, le point de terminaison répond 401. Créez une clé sur la page Développeurs.

Configuration du point de terminaison hébergéjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Le serveur hébergé liste sept outils : pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload et pdf_toolbox_download. Chaque outil de catégorie prend un nom d'operation et ses paramètres, plus un fichier ou un fileId renvoyé par l'outil d'envoi. Utilisez l'outil describe pour obtenir le schéma d'une opération.

FAQ

Qu'est-ce que MCP ?

MCP, le Model Context Protocol, est un standard ouvert pour connecter des clients IA à des outils externes. Un client comme Claude Code lance un serveur MCP ou le contacte, liste ses outils et les appelle au nom de l'utilisateur.

Le serveur MCP local fonctionne-t-il hors ligne ?

Non. Il envoie les fichiers à l'API PDF123, ou au serveur indiqué dans PDFX_API_BASE, et enregistre le résultat en local. La base de l'API doit être joignable.

Faut-il une clé d'API ?

Le serveur local n'exige pas de clé en usage anonyme. Définissez PDFX_API_KEY si votre serveur en exige une. Le point de terminaison hébergé sur /mcp exige toujours un en-tête X-API-KEY.

L'agent peut-il lire n'importe quel fichier de mon ordinateur ?

Par défaut, il peut lire tout chemin que le processus du serveur peut atteindre. Définissez PDFX_MCP_ROOT pour limiter la lecture et l'écriture aux répertoires de votre choix.

Que deviennent mes fichiers ?

Le serveur local envoie chaque entrée à l'API PDF123, ou à votre propre serveur, pour traitement. La description de l'outil indique que les fichiers y sont supprimés après le traitement. Le résultat est enregistré sur votre machine. Pour plus de détails, lisez la page sur la confidentialité des fichiers.

Combien d'outils un agent peut-il utiliser ?

Le serveur local donne accès aux 97 outils du catalogue à travers cinq outils MCP. Le point de terminaison hébergé regroupe ses opérations par catégorie (convert, pages, misc et security) derrière sept outils MCP.