API & Automatisierung
PDF Content Search bietet eine umfangreiche Programmierschnittstelle für die Integration mit Automatisierungs-Skripten, KI-Assistenten und eigenen Anwendungen.
REST API
Der integrierte HTTP-Server stellt über 70 Endpunkte unter http://127.0.0.1:44477/api/v1/ bereit. Die API deckt folgende Bereiche ab:
- Suche: Volltextsuche, Dokumenttext, Metadaten, Batch-Export
- Ordner: Ordner auflisten, Inhalte anzeigen, Verarbeitungsstatus
- Dokumente: Metadaten, Thumbnails, OCR-Bounding-Boxes, Neu-Verarbeitung
- Einstellungen: Lesen und Ändern von App-Einstellungen
- UI-Steuerung: Navigation, Zoom, Seitenwechsel, Filter, Sortierung, Screenshot
- Mobile Sync: Status verbundener Geräte, Synchronisation auslösen
- Cloud: Status und Steuerung der Office-Umwandlung
- Mail: Apple-Mail-Suche, Mail-Inhalte, Anhänge und Indexstatus
- Lizenz: Lizenzstatus abfragen und abgleichen
Die vollständige API-Dokumentation ist interaktiv verfügbar unter http://127.0.0.1:44477/api/v1/docs. Die OpenAPI-Spezifikation kann unter http://127.0.0.1:44477/api/v1/openapi.yaml abgerufen werden.
Authentifizierung
Jede Anfrage braucht ein Bearer-Token. Sie erzeugen es unter Einstellungen → Integrationen → Für Entwickler: REST-API und Server mit Generieren und übernehmen es mit Kopieren. Ohne Token erreichbar sind nur /api/v1/health, /api/v1/docs und /api/v1/openapi.yaml. Ist Port 44477 belegt, weicht die App auf 44478 oder 44479 aus.
curl -H "Authorization: Bearer IHR_TOKEN" \
http://127.0.0.1:44477/api/v1/search \
-d '{"query": "Rechnung 2024"}'MCP (Model Context Protocol)
Für die Integration mit KI-Assistenten wie Claude unterstützt die App das Model Context Protocol (MCP) über JSON-RPC 2.0 am Endpunkt /mcp. Die wichtigsten Werkzeuge im Überblick; die vollständige Liste folgt im nächsten Abschnitt:
| Kategorie | Tools |
|---|---|
| Suche | search_documents, get_document_text, get_document_metadata, export_documents |
| Ordner | list_folders, list_folder_contents, get_processing_status |
| UI-Steuerung | ui_navigate, ui_select_document, show_in_app, ui_search, get_ui_state, get_search_state, ui_screenshot |
| Dateien | open_in_finder, open_document_external, get_document_thumbnail |
| Verarbeitung | reprocess_document, rescan_folder |
| Konfiguration | get_app_status, get_settings |
| search_mail, list_inbox, get_mail_body, create_mail_draft | |
| Lizenz | get_license_status, refresh_license |
| Handbuch | search_manual, get_manual_section |
MCP verwendet die gleiche Bearer-Token-Authentifizierung wie die REST API.
Anhänge für Mail-Entwürfe von einem anderen Rechner. create_mail_draft legt den Entwurf auf dem Mac an, auf dem die App läuft. Ein Dateipfad gilt deshalb nur dort. Läuft der KI-Assistent auf einem anderen Rechner, zum Beispiel in einer virtuellen Maschine, lädt er die Datei zuerst hoch: POST /api/v1/mail/attachments?filename=<Name> mit den rohen Bytes als Body und demselben Token. Die Antwort enthält eine attachment_id, die er dann als Anhang übergibt. Ein Upload gilt 30 Minuten, höchstens 20 MB je Datei, und wird vom Entwurf verbraucht.
curl -H "Authorization: Bearer IHR_TOKEN" --data-binary @paket.zip \
"http://IHR-MAC.local:44477/api/v1/mail/attachments?filename=paket.zip"MCP-Werkzeuge (Übersicht)
Die folgende Übersicht listet alle MCP-Werkzeuge der App, gruppiert nach Bereich. Werkzeuge mit dem Vermerk „(erfordert Bestätigung)“ verändern Daten unwiderruflich oder berühren Lizenz- bzw. Kopplungsstatus und verlangen confirm: true.
Suche & Dokumente
| Werkzeug | Funktion |
|---|---|
search_documents | Volltextsuche über alle indizierten Dokumente und Apple-Mail-Nachrichten, unabhängig von den Häkchen in der App; eingrenzbar mit folders (Pfade hinzugefügter Ordner) und source_types |
get_document_text | OCR-Volltext eines Dokuments seitenweise abrufen |
get_document_metadata | Metadaten eines Dokuments (Name, Pfad, Seiten, Status) |
get_document_thumbnail | PNG-Vorschau einer Dokumentseite (Base64) |
get_document_ocr_rects | OCR-Trefferrechtecke eines Dokuments abrufen |
get_document_by_path | Indiziertes Dokument zu einem absoluten Dateipfad finden (ID, Verarbeitungsstand) |
export_documents | OCR-Text und Metadaten mehrerer Dokumente exportieren |
reprocess_document | Dokument erneut für OCR einreihen |
delete_document | Einzelnes Dokument aus dem Index löschen (erfordert Bestätigung) |
bulk_delete_documents | Mehrere Dokumente auf einmal aus dem Index löschen (erfordert Bestätigung) |
Ordner & Verarbeitung
| Werkzeug | Funktion |
|---|---|
list_folders | Alle indizierten Ordner auflisten |
list_folder_contents | Dokumente eines Ordners auflisten (paginiert) |
get_folder_stats | Kennzahlen eines Ordners (Dokumente, Seiten, Status) |
get_folder_processing_status | OCR-Verarbeitungsstatus eines Ordners |
add_folder | Ordner per absolutem Pfad zum Index hinzufügen |
delete_folder | Ordner aus dem Index entfernen (erfordert Bestätigung) |
rescan_folder | Ordner auf neue/geänderte Dateien prüfen |
get_processing_status | OCR-Statistik über alle Dokumente und Ordner |
get_processing_progress | Laufenden OCR-Fortschritt abfragen |
Scans
| Werkzeug | Funktion |
|---|---|
list_recent_scans | Zuletzt gescannte Objekte auflisten |
get_unread_scan_count | Anzahl noch ungelesener Scans |
mark_scan_as_read | Einen Scan als gelesen markieren |
Mail & Anhänge
| Werkzeug | Funktion |
|---|---|
search_mail | Volltextsuche nur in Apple-Mail-Nachrichten (Betreff, Text, Anhänge) |
list_inbox | Mails im Posteingang auflisten (alle Konten) |
get_mail_body | Vollständigen Text einer Mail samt Link-Zielen abrufen |
get_mail_raw | Originalquelltext einer Mail (RFC 822) mit allen Kopfzeilen abrufen |
create_mail_draft | Entwurf oder Antwort in Apple Mail anlegen; sendet nie selbst |
get_mail_message_metadata | Kopf- und Postfach-Metadaten einer Mail (Message-ID) |
open_in_apple_mail | Mail in Apple Mail öffnen (nur am selben Mac) |
get_mail_index_status | Status des Apple-Mail-Indexers |
get_mail_recent | Zuletzt indizierte Mails auflisten |
get_mail_mailboxes | Postfächer aus dem Apple-Mail-Index auflisten |
setup_apple_mail | Apple-Mail-Indizierung einrichten und aktivieren |
disable_apple_mail | Apple-Mail-Indizierung deaktivieren |
clear_mail_index | Mail-Index leeren und Cursor zurücksetzen |
reindex_apple_mail | Indexer-Lauf auslösen |
get_mail_full_index_status | Zähler über alle Mail-Datensätze (Vollständigkeit) |
list_incomplete_mails | Nicht erfolgreich indizierte Mails auflisten |
retry_incomplete_mails | Unvollständige Mails erneut indizieren |
cleanup_stale_mail_meta | Veraltete Mail-Datensätze bereinigen |
list_mail_cloud_jobs | Cloud-Jobs für Office-Anhänge auflisten |
retry_failed_mail_cloud_jobs | Fehlgeschlagene Cloud-Jobs erneut versuchen |
cancel_pending_mail_cloud_jobs | Ausstehende Cloud-Jobs abbrechen |
tick_mail_cloud_worker | Cloud-Worker sofort ausführen |
get_mail_detail | Vollständige Details einer indizierten Mail |
get_mail_by_rowid | Indizierte Mail per Rowid abrufen |
reveal_mail_in_finder | Die .emlx-Datei im Finder zeigen (nur am selben Mac) |
list_mail_attachments | Anhänge einer indizierten Mail auflisten |
get_mail_attachment | Einen Anhang einer Mail abrufen |
Einstellungen
| Werkzeug | Funktion |
|---|---|
get_settings | Aktuelle App-Einstellungen abrufen |
patch_settings_search | Sucheinstellungen ändern |
patch_settings_processing | OCR-/Verarbeitungseinstellungen ändern |
patch_settings_appearance | Darstellungseinstellungen ändern |
patch_settings_sharing | Einstellungen für mobile Freigabe ändern |
UI-Steuerung
| Werkzeug | Funktion |
|---|---|
get_ui_state | Aktuellen UI-Zustand abfragen |
get_search_state | Animierte OCR-Treffer in der Vorschau abfragen |
ui_search | Suche in der App-Oberfläche auslösen (durchsucht die in der App angehakten Ordner) |
ui_navigate | In der Dokumentliste navigieren |
ui_select_document | Dokument in der Liste auswählen |
show_in_app | Dokument in der App zeigen: App nach vorn, Suche mit Markierungen, Seite mit dem Treffer öffnen |
ui_screenshot | Screenshot des Hauptfensters |
open_in_finder | Dokument im Finder zeigen (nur am selben Mac) |
open_document_external | Dokument extern öffnen (nur am selben Mac) |
ui_list_items | Sichtbare Listeneinträge auflisten |
ui_get_zoom | Zoom-Zustand der Vorschau abfragen |
ui_set_zoom | Zoom der Vorschau setzen |
ui_get_page | Aktuelle Seite der Vorschau abfragen |
ui_set_page | Seite der Vorschau wechseln |
ui_get_transcript | Zustand des Transkript-Panels abfragen |
ui_set_transcript | Transkript-Panel ein-/ausblenden |
ui_get_sort | Aktuelle Sortierung abfragen |
ui_set_sort | Listensortierung setzen |
ui_get_filters | Aktive Listenfilter abfragen |
ui_set_filters | Listenfilter setzen |
ui_get_popups | Offene Popups/Sheets auflisten |
ui_dismiss_popup | Ein Popup/Sheet schließen |
ui_list_alerts | Offene Hinweisdialoge auflisten |
ui_dismiss_alert | Hinweisdialoge schließen |
Lizenz
| Werkzeug | Funktion |
|---|---|
get_license_status | Aktuellen Lizenzstatus abrufen |
refresh_license | Lizenzstatus mit dem Server abgleichen |
activate_license | Lizenzschlüssel aktivieren, nur Direktvertrieb (erfordert Bestätigung) |
deactivate_license | Aktuelle Lizenz deaktivieren, nur Direktvertrieb (erfordert Bestätigung) |
request_trial | Testschlüssel per E-Mail anfordern, nur Direktvertrieb (erfordert Bestätigung) |
activate_license erwartet license_key, email und owner_name, also die Angaben aus der Kauf- oder Test-E-Mail. request_trial erwartet email und owner_name; der Lizenzserver schickt den Testschlüssel an diese Adresse, höchstens eine E-Mail alle zwei Minuten. Aktiviert wird der Schlüssel danach über den Link in der E-Mail oder mit activate_license. Beide Werkzeuge verlangen confirm: true und funktionieren erst, wenn Sie im Lizenzfenster der App AGBs und Datenschutzbestimmungen akzeptieren gewählt haben.
Cloud
| Werkzeug | Funktion |
|---|---|
get_cloud_status | Status des Cloud-Dienstes abrufen |
list_cloud_items | Objekte des Cloud-Dienstes auflisten |
cloud_sync | Cloud-Dienst steuern (ein/aus, Aufräumen) |
Mobile
| Werkzeug | Funktion |
|---|---|
get_mobile_sync_status | Status der mobilen Synchronisierung |
list_mobile_devices | Mit Geräten geteilte Ordner auflisten |
mobile_sync | Mobile Synchronisierung auslösen |
confirm_mobile_pairing | Geräte-Kopplung mit 9-stelligem Code bestätigen (erfordert Bestätigung) |
App-Status
| Werkzeug | Funktion |
|---|---|
get_app_status | Status, Version, Laufzeit und Port der App |
Handbuch
| Werkzeug | Funktion |
|---|---|
search_manual | Im eingebauten Handbuch suchen (Deutsch oder Englisch) |
get_manual_section | Einen Handbuchabschnitt vollständig abrufen |
Claude Desktop einrichten (ein Klick)
Für Claude Desktop bringt PDF Content Search einen Ein-Klick-Installer mit, der sich um die komplette Konfiguration kümmert — ohne dass Sie JSON-Dateien editieren müssen.
Voraussetzung: Claude Desktop ist installiert (claude.ai/download).
- In PDF Content Search: Einstellungen → Integrationen → Abschnitt „KI-Assistenten (MCP)“
- Auf „In Claude Desktop einrichten“ klicken
- Den Erklärungs-Dialog mit „Weiter“ bestätigen (macOS benötigt einmalig die Erlaubnis, Claudes Konfigurationsdatei zu schreiben)
- Im Finder-Fenster die bereits markierte Datei
claude_desktop_config.jsonauswählen und auf „Zugriff gewähren“ klicken - Claude Desktop neu starten; die App bietet das mit „Jetzt neu starten“ direkt an
Im Hintergrund aktiviert die App automatisch den API-Server, erzeugt ein sicheres Zugriffs-Token, trägt den Server-Eintrag in ~/Library/Application Support/Claude/claude_desktop_config.json ein und verweist auf das mitgelieferte Hilfsprogramm pdf-content-search-mcp im App-Bundle, das als Brücke zwischen Claude Desktops stdio-Transport und dem HTTP-MCP-Server der App dient. Liegt die App später an einem anderen Ort oder ändern sich Token oder Port, meldet das die Statuszeile; klicken Sie dann auf „Eintrag in Claude Desktop aktualisieren“.
Bereits vorhandene Einträge in mcpServers oder andere Top-Level-Keys bleiben unverändert — der Installer macht einen sauberen JSON-Merge. Zum Entfernen steht im gleichen Abschnitt ein Button „Aus Claude Desktop entfernen“ bereit.
Andere MCP-Clients (z. B. Claude Code oder eigene Integrationen, die HTTP-Transport unterstützen) können den Server weiterhin direkt über HTTP ansprechen. Adresse und beide Konfigurationen (HTTP und stdio) zeigt die App unter „Andere Apps“ mit „Verbindung einrichten …“.
Anwendungsbeispiele
- Automatisierungs-Skripte: Dokumente per REST API durchsuchen und Ergebnisse weiterverarbeiten
- KI-Assistenten: Claude oder andere LLMs können über MCP direkt auf Ihre Dokumente zugreifen
- Eigene Integrationen: Über die OpenAPI-Spezifikation können Client-Bibliotheken generiert werden