Zum Hauptinhalt springen
PPDF123

PDF123-MCP-Server für KI-Agenten

MCP, das Model Context Protocol, ist ein offener Standard, mit dem KI-Clients wie Claude Code, Claude Desktop und Cursor externe Werkzeuge aufrufen. PDF123 bietet einen lokalen MCP-Server, @pdf123/mcp, für Dateien auf Ihrem Rechner und einen gehosteten Endpunkt, der einen API-Schlüssel verwendet.

@pdf123/mcpNode 20.3 oder neuer

Installation

npx -y @pdf123/mcp
Auf dieser Seite

Welchen MCP-Server soll ich verwenden?

Beide Server stellen PDF123-Operationen bereit. Sie unterscheiden sich darin, wo sie laufen und wie die Dateien zu ihnen gelangen.

Lokal: @pdf123/mcpGehostet: /mcp
LäuftAuf Ihrem Rechner, vom MCP-Client über stdio gestartetAuf den PDF123-Servern unter https://pdf123.xyz/mcp
EingabeDateipfade auf der Festplatte. Der Server lädt sie hoch und speichert das Ergebnis neben der EingabeDateien, die über das Upload-Werkzeug gesendet werden
ZugangsdatenBei anonymer Nutzung keine. PDFX_API_KEY ist optionalHeader X-API-KEY bei jeder Anfrage. Ohne ihn lautet die Antwort 401
Installationnpx -y @pdf123/mcpKeine. Fügen Sie dem Client die URL und den Header hinzu
WerkzeugeFünf Werkzeuge für den gesamten Katalog mit 97 WerkzeugenSieben Werkzeuge: describe, convert, pages, misc, security, upload und download
Geeignet, wennEin Agent mit Dokumenten in einem lokalen Ordner arbeitetEin Agent oder gehosteter Dienst Uploads bereits über die API abwickelt

Nutzen Sie den lokalen Server für Coding-Assistenten auf einem Laptop. Nutzen Sie den gehosteten Endpunkt, wenn der Agent in der Cloud läuft und Ihre Festplatte nicht lesen kann.

Wie installiere ich den lokalen MCP-Server?

Es muss nichts installiert werden, denn der MCP-Client startet den Server mit npx. In Claude Code fügen Sie ihn mit einem Befehl hinzu.

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

Claude Desktop liest claude_desktop_config.json, Cursor liest .cursor/mcp.json. Andere Clients haben eine MCP-Einstellungsseite oder -Datei. Alle akzeptieren denselben Eintrag mcpServers.

MCP-Client-Konfigurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Starten Sie den Client nach einer Konfigurationsänderung neu. Um eine Kopie im Pfad zu behalten, führen Sie npm install -g @pdf123/mcp aus; das stellt den Befehl pdf123-mcp bereit. Der Server braucht Node 20.3 oder neuer und eine erreichbare API-Basis. Einen Offline-Modus gibt es nicht.

Was frage ich den Agenten zuerst?

Fragen Sie in normaler Sprache und nennen Sie die Dateien. Zum Beispiel:

Führe ~/Documents/a.pdf und ~/Documents/b.pdf zusammen und komprimiere dann das Ergebnis.

Der Agent ruft pdf123_run_pipeline oder zweimal pdf123_run_tool auf, lädt die Dateien zu PDF123 hoch und antwortet mit dem Pfad der gespeicherten Datei. Das Ergebnis wird neben der ersten Eingabe gespeichert und ersetzt nie eine vorhandene Datei. Dieselben Operationen gibt es auf der Website als Zusammenführen und Komprimieren.

Welche Werkzeuge bietet der lokale Server?

Der Server hat fünf Werkzeuge. Werkzeug-IDs wie merge sind einfache String-Argumente, daher bleibt die Werkzeugliste klein.

WerkzeugFunktionWichtige Argumente
pdf123_list_toolsListet die Werkzeuge auf, eine Zeile pro Werkzeuggroup, query, format
pdf123_describe_toolZeigt Felder, Standardwerte und erlaubte Werte eines Werkzeugs und ob es als Stapel läufttool
pdf123_run_toolFührt ein Werkzeug auf lokalen Dateien aus und liefert den gespeicherten Pfad oder den JSON-Berichttool, files, params, output
pdf123_run_pipelineVerkettet bis zu 8 Werkzeuge in einer Anfragesteps, files, output
pdf123_callSendet eine Rohanfrage an eine beliebige Werkzeug-ID, Operations-ID oder einen /api/...-Pfadtarget, files, fields

Ein Agent ruft meist pdf123_list_tools auf, um ein Werkzeug zu finden, dann pdf123_describe_tool, um dessen Felder zu lesen, und schließlich pdf123_run_tool. Bei einer vertippten ID erhält er Vorschläge im Stil von „meinten Sie“.

Wie funktionieren Stapel, Passwörter und Pipelines?

  • Stapel. Mehrere Dateien, die einem Einzeldatei-Werkzeug übergeben werden, laufen als Stapel mit einem Ergebnis pro Datei. Jede Datei wird gespeichert, sobald sie fertig ist. Die Antwort ist ein Bericht pro Datei. Schlägt eine Datei fehl, ist die Antwort ein Fehler mit angehängtem Bericht, sodass der Agent nur die fehlgeschlagenen Dateien wiederholen kann.
  • Passwörter. input_password öffnet jede verschlüsselte Eingabe. passwords legt ein Passwort pro Datei fest, in derselben Reihenfolge wie files, mit einer leeren Zeichenfolge für eine nicht geschützte Datei. Das funktioniert auch bei Werkzeugen mit mehreren Dateien wie Zusammenführen.
  • Pipelines. pdf123_run_pipeline nimmt bis zu 8 Schritte entgegen, und jeder Schritt speist den nächsten. Es akzeptiert dieselben Passwort-Argumente.
  • Rohaufrufe. pdf123_call erreicht Operationen, die neuer sind als der Server. Lokal wird nichts validiert.
  • Filter-Werkzeuge. Ein Werkzeug, dessen ID mit filter- beginnt, antwortet mit {"matched": false}, wenn seine Bedingung nicht zutrifft. Das ist ein Ergebnis, kein Fehler.
  • Wiederholungen. idempotencyKey liefert 24 Stunden lang das erste Ergebnis erneut.

Wie beschränke ich die Ordner, die der Agent nutzen darf?

Setzen Sie PDFX_MCP_ROOT auf ein Verzeichnis. Mehrere Verzeichnisse trennen Sie mit einem Doppelpunkt, unter Windows mit einem Semikolon. Der Server liest Eingaben und schreibt Ergebnisse dann nur innerhalb dieser Verzeichnisse. Pfade außerhalb, ..-Ausbrüche und symbolische Links, die hinausführen, werden abgelehnt, bevor etwas hochgeladen wird, mit Code: path_not_allowed. Ohne diese Variable ist jeder Pfad erlaubt, den der Serverprozess erreichen kann.

Dateizugriff einschränkenjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Setzen Sie Umgebungsvariablen im Block env des Clients oder mit claude mcp add -e NAME=value. Mit PDFX_API_BASE richten Sie den Server stattdessen auf Ihren eigenen pdfx-server; siehe Self-Host.

Wie sehen Ergebnisse und Fehler aus?

Ein einzelnes Ergebnis ist ein kleines JSON-Objekt mit dem gespeicherten path, dem contentType und der Größe in bytes. Ein Stapelergebnis hat processed, unmatched, failed und eine Liste files. Diese Formen entsprechen pdfx --json auf der Kommandozeile. Ein Werkzeug, das einen Bericht liefert, etwa Dokumentinfo, gibt den Bericht direkt zurück.

Einzelnes Ergebnisjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Ein fehlgeschlagener Aufruf kommt als Werkzeugfehler zurück. Sein Text endet mit den Zeilen Reason:, Code: und Hint:, sofern der Server sie geliefert hat, sodass ein Agent anhand des Codes verzweigen kann.

Fehlertexttext
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.

Hat eine Werkzeug-ID einen Tippfehler, listet der Fehler ähnliche IDs auf und endet mit Code: unknown_tool. Ein Werkzeug, das nichts zurückzugeben hat, etwa pdf-to-csv bei einer PDF ohne Tabellen, liefert Code: no_content statt einer leeren Datei. Siehe Fehlercodes.

Wie nutze ich den gehosteten MCP-Endpunkt?

Die API bettet einen MCP-Server unter POST https://pdf123.xyz/mcp ein. Authentifizieren Sie sich mit demselben Header X-API-KEY, den die REST-API verwendet. Ohne Schlüssel antwortet der Endpunkt mit 401. Einen Schlüssel erstellen Sie auf der Entwicklerseite.

Konfiguration des gehosteten Endpunktsjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Der gehostete Server listet sieben Werkzeuge: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload und pdf_toolbox_download. Jedes Kategorie-Werkzeug nimmt einen Namen operation und dessen Parameter entgegen, dazu eine Datei oder eine fileId, die das Upload-Werkzeug zurückgibt. Mit dem Describe-Werkzeug erhalten Sie das Schema einer Operation.

FAQ

Was ist MCP?

MCP, das Model Context Protocol, ist ein offener Standard, um KI-Clients mit externen Werkzeugen zu verbinden. Ein Client wie Claude Code startet einen MCP-Server oder nimmt Kontakt zu ihm auf, listet dessen Werkzeuge auf und ruft sie im Auftrag des Nutzers auf.

Funktioniert der lokale MCP-Server offline?

Nein. Er lädt Dateien zur PDF123-API oder zu dem Server hoch, der in PDFX_API_BASE angegeben ist, und speichert das Ergebnis lokal. Die API-Basis muss erreichbar sein.

Braucht er einen API-Schlüssel?

Der lokale Server braucht bei anonymer Nutzung keinen Schlüssel. Setzen Sie PDFX_API_KEY, wenn Ihr Server einen verlangt. Der gehostete Endpunkt unter /mcp braucht immer einen Header X-API-KEY.

Kann der Agent jede Datei auf meinem Computer lesen?

Standardmäßig kann er jeden Pfad lesen, den der Serverprozess erreicht. Setzen Sie PDFX_MCP_ROOT, um Lese- und Schreibzugriffe auf die von Ihnen gewählten Verzeichnisse zu beschränken.

Was geschieht mit meinen Dateien?

Der lokale Server lädt jede Eingabe zur Verarbeitung zur PDF123-API oder zu Ihrem eigenen Server hoch. In der Werkzeugbeschreibung steht, dass die Dateien dort nach der Verarbeitung gelöscht werden. Das Ergebnis wird auf Ihrem Rechner gespeichert. Einzelheiten stehen auf der Seite Dateischutz.

Wie viele Werkzeuge kann ein Agent nutzen?

Der lokale Server erreicht über fünf MCP-Werkzeuge alle 97 Werkzeuge des Katalogs. Der gehostete Endpunkt gruppiert seine Operationen nach Kategorie (convert, pages, misc und security) hinter sieben MCP-Werkzeugen.