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/mcp | Gehostet: /mcp | |
|---|---|---|
| Läuft | Auf Ihrem Rechner, vom MCP-Client über stdio gestartet | Auf den PDF123-Servern unter https://pdf123.xyz/mcp |
| Eingabe | Dateipfade auf der Festplatte. Der Server lädt sie hoch und speichert das Ergebnis neben der Eingabe | Dateien, die über das Upload-Werkzeug gesendet werden |
| Zugangsdaten | Bei anonymer Nutzung keine. PDFX_API_KEY ist optional | Header X-API-KEY bei jeder Anfrage. Ohne ihn lautet die Antwort 401 |
| Installation | npx -y @pdf123/mcp | Keine. Fügen Sie dem Client die URL und den Header hinzu |
| Werkzeuge | Fünf Werkzeuge für den gesamten Katalog mit 97 Werkzeugen | Sieben Werkzeuge: describe, convert, pages, misc, security, upload und download |
| Geeignet, wenn | Ein Agent mit Dokumenten in einem lokalen Ordner arbeitet | Ein 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 mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop liest claude_desktop_config.json, Cursor liest .cursor/mcp.json. Andere Clients haben eine MCP-Einstellungsseite oder -Datei. Alle akzeptieren denselben Eintrag mcpServers.
{
"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.
| Werkzeug | Funktion | Wichtige Argumente |
|---|---|---|
pdf123_list_tools | Listet die Werkzeuge auf, eine Zeile pro Werkzeug | group, query, format |
pdf123_describe_tool | Zeigt Felder, Standardwerte und erlaubte Werte eines Werkzeugs und ob es als Stapel läuft | tool |
pdf123_run_tool | Führt ein Werkzeug auf lokalen Dateien aus und liefert den gespeicherten Pfad oder den JSON-Bericht | tool, files, params, output |
pdf123_run_pipeline | Verkettet bis zu 8 Werkzeuge in einer Anfrage | steps, files, output |
pdf123_call | Sendet eine Rohanfrage an eine beliebige Werkzeug-ID, Operations-ID oder einen /api/...-Pfad | target, 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.passwordslegt ein Passwort pro Datei fest, in derselben Reihenfolge wiefiles, 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_pipelinenimmt bis zu 8 Schritte entgegen, und jeder Schritt speist den nächsten. Es akzeptiert dieselben Passwort-Argumente. - Rohaufrufe.
pdf123_callerreicht 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.
idempotencyKeyliefert 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.
"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.
{
"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.
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.
{
"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.
Weiterführende Seiten
- Agent-Skills für Claude Code, Codex und Cursor, einer für den Katalog und einer pro Werkzeug
- /llms.txt, ein Klartext-Index der Werkzeuge, der API und des MCP-Endpunkts
- Kommandozeile pdfx und TypeScript-SDK, die sich den Katalog teilen
- Entwicklerübersicht, das OpenAPI-Dokument und Swagger UI
- Werkzeugseiten: Zusammenführen, Komprimieren, OCR, Schützen, Reparieren
- Die Beiträge „Built for AI Agents, Not Just Browsers“ und „Same Operation, Four Clients“ im PDF123-Blog
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.