API & Automation
PDF Content Search provides a comprehensive programming interface for integration with automation scripts, AI assistants and custom applications.
REST API
The built-in HTTP server provides over 70 endpoints at http://127.0.0.1:44477/api/v1/. The API covers the following areas:
- Search: Full-text search, document text, metadata, batch export
- Folders: List folders, view contents, processing status
- Documents: Metadata, thumbnails, OCR bounding boxes, reprocessing
- Settings: Read and modify app settings
- UI Control: Navigation, zoom, page switching, filters, sorting, screenshot
- Mobile Sync: Connected device status, trigger synchronization
- Cloud: Status and control of Office conversion
- Mail: Apple Mail search, mail content, attachments and index status
- License: Query and refresh the license status
The full API documentation is available interactively at http://127.0.0.1:44477/api/v1/docs. The OpenAPI specification can be retrieved at http://127.0.0.1:44477/api/v1/openapi.yaml.
Authentication
Every request needs a Bearer token. Create it under Settings → Integrations → For developers: REST API and server with Generate and take it over with Copy. Only /api/v1/health, /api/v1/docs and /api/v1/openapi.yaml are accessible without a token. If port 44477 is in use, the app falls back to 44478 or 44479.
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://127.0.0.1:44477/api/v1/search \
-d '{"query": "invoice 2024"}'MCP (Model Context Protocol)
For integration with AI assistants like Claude, the app supports the Model Context Protocol (MCP) via JSON-RPC 2.0 at the /mcp endpoint. The most important tools at a glance; the complete list follows in the next section:
| Category | Tools |
|---|---|
| Search | search_documents, get_document_text, get_document_metadata, export_documents |
| Folders | list_folders, list_folder_contents, get_processing_status |
| UI Control | ui_navigate, ui_select_document, show_in_app, ui_search, get_ui_state, get_search_state, ui_screenshot |
| Files | open_in_finder, open_document_external, get_document_thumbnail |
| Processing | reprocess_document, rescan_folder |
| Config | get_app_status, get_settings |
| search_mail, list_inbox, get_mail_body, create_mail_draft | |
| License | get_license_status, refresh_license |
| Manual | search_manual, get_manual_section |
MCP uses the same Bearer token authentication as the REST API.
Attachments for mail drafts from another machine. create_mail_draft creates the draft on the Mac the app runs on, so a file path only works there. If the AI assistant runs on another machine, for example in a virtual machine, it uploads the file first: POST /api/v1/mail/attachments?filename=<name> with the raw bytes as the body and the same token. The response contains an attachment_id, which it then passes as the attachment. An upload is kept for 30 minutes, up to 20 MB per file, and is used up by the draft.
curl -H "Authorization: Bearer YOUR_TOKEN" --data-binary @package.zip \
"http://YOUR-MAC.local:44477/api/v1/mail/attachments?filename=package.zip"MCP Tools (Overview)
The overview below lists every MCP tool of the app, grouped by area. Tools marked “(requires confirmation)” change data irreversibly or touch license/pairing state and require confirm: true.
Search & Documents
| Tool | Function |
|---|---|
search_documents | Full-text search across all indexed documents and Apple Mail messages, independent of the checkboxes in the app; narrow it with folders (paths of added folders) and source_types |
get_document_text | Get a document's full OCR text, by page |
get_document_metadata | Document metadata (name, path, pages, state) |
get_document_thumbnail | PNG thumbnail of a document page (base64) |
get_document_ocr_rects | OCR bounding boxes of a document |
get_document_by_path | Find the indexed document for an absolute file path (ID, processing state) |
export_documents | Export OCR text and metadata for multiple documents |
reprocess_document | Re-queue a document for OCR |
delete_document | Delete a single document from the index (requires confirmation) |
bulk_delete_documents | Delete multiple documents at once (requires confirmation) |
Folders & Processing
| Tool | Function |
|---|---|
list_folders | List all indexed folders |
list_folder_contents | List documents in a folder (paginated) |
get_folder_stats | Aggregate stats for a folder |
get_folder_processing_status | OCR processing status of a folder |
add_folder | Add a folder to the index by absolute path |
delete_folder | Remove a folder from the index (requires confirmation) |
rescan_folder | Rescan a folder for new or changed files |
get_processing_status | OCR statistics across all documents and folders |
get_processing_progress | Live OCR processing progress |
Scans
| Tool | Function |
|---|---|
list_recent_scans | List recently scanned items |
get_unread_scan_count | Count of unread recent scans |
mark_scan_as_read | Mark a recent scan as read |
Mail & Attachments
| Tool | Function |
|---|---|
search_mail | Full-text search in Apple Mail messages only (subject, body, attachments) |
list_inbox | List the emails in the inbox (all accounts) |
get_mail_body | Fetch the complete text of a mail with its link targets |
get_mail_raw | Fetch the original source of a mail (RFC 822) with all headers |
create_mail_draft | Create a draft or reply in Apple Mail; never sends |
get_mail_message_metadata | Header/mailbox metadata of a mail (message-id) |
open_in_apple_mail | Open a mail in Apple Mail (same Mac only) |
get_mail_index_status | Apple Mail indexer status |
get_mail_recent | List most recently indexed mails |
get_mail_mailboxes | List mailboxes from the Apple Mail index |
setup_apple_mail | Configure and enable Apple Mail indexing |
disable_apple_mail | Disable Apple Mail indexing |
clear_mail_index | Clear the mail index and reset the cursor |
reindex_apple_mail | Trigger an indexer run |
get_mail_full_index_status | Counters across all mail records (completeness) |
list_incomplete_mails | List mails not successfully indexed |
retry_incomplete_mails | Retry indexing of incomplete mails |
cleanup_stale_mail_meta | Garbage-collect stale mail records |
list_mail_cloud_jobs | List Office-attachment cloud jobs |
retry_failed_mail_cloud_jobs | Retry failed cloud jobs |
cancel_pending_mail_cloud_jobs | Cancel pending cloud jobs |
tick_mail_cloud_worker | Trigger an immediate cloud-worker tick |
get_mail_detail | Full detail of an indexed mail |
get_mail_by_rowid | Get an indexed mail by rowid |
reveal_mail_in_finder | Reveal the .emlx file in Finder (same Mac only) |
list_mail_attachments | List attachments of an indexed mail |
get_mail_attachment | Fetch a single attachment of a mail |
Settings
| Tool | Function |
|---|---|
get_settings | Get current app settings |
patch_settings_search | Update search settings |
patch_settings_processing | Update OCR/processing settings |
patch_settings_appearance | Update appearance settings |
patch_settings_sharing | Update mobile-sharing settings |
UI Control
| Tool | Function |
|---|---|
get_ui_state | Get current UI state |
get_search_state | Get animated OCR hits in the preview |
ui_search | Trigger a search in the app UI (covers the folders checked in the app) |
ui_navigate | Navigate within the document list |
ui_select_document | Select a document in the list |
show_in_app | Show a document in the app: brings the app to the front, runs the search with highlights, opens the page with the match |
ui_screenshot | Screenshot of the main window |
open_in_finder | Reveal a document in Finder (same Mac only) |
open_document_external | Open a document externally (same Mac only) |
ui_list_items | List items currently shown in the list |
ui_get_zoom | Get the preview zoom state |
ui_set_zoom | Set the preview zoom |
ui_get_page | Get the current preview page |
ui_set_page | Navigate the preview page |
ui_get_transcript | Get the transcript panel state |
ui_set_transcript | Show/hide the transcript panel |
ui_get_sort | Get the current sort order |
ui_set_sort | Set the list sort order |
ui_get_filters | Get active list filters |
ui_set_filters | Set list filters |
ui_get_popups | List open popups/sheets |
ui_dismiss_popup | Dismiss a popup/sheet |
ui_list_alerts | List open alerts |
ui_dismiss_alert | Dismiss alerts |
License
| Tool | Function |
|---|---|
get_license_status | Get current license status |
refresh_license | Re-sync license status with the server |
activate_license | Activate a license key, direct-download version only (requires confirmation) |
deactivate_license | Deactivate the current license, direct-download version only (requires confirmation) |
request_trial | Request a trial key by email, direct-download version only (requires confirmation) |
activate_license expects license_key, email and owner_name, i.e. the details from the purchase or trial email. request_trial expects email and owner_name; the license server sends the trial key to that address, at most one email every two minutes. You then activate the key via the link in the email or with activate_license. Both tools require confirm: true and only work after you have selected Agree to terms and conditions in the app's license window.
Cloud
| Tool | Function |
|---|---|
get_cloud_status | Get cloud-service status |
list_cloud_items | List cloud-service items |
cloud_sync | Control the cloud service (toggle, cleanup) |
Mobile
| Tool | Function |
|---|---|
get_mobile_sync_status | Mobile-sync status |
list_mobile_devices | List folders shared with mobile devices |
mobile_sync | Trigger a mobile sync |
confirm_mobile_pairing | Confirm device pairing with a 9-digit code (requires confirmation) |
App Status
| Tool | Function |
|---|---|
get_app_status | App status, version, uptime and port |
Manual
| Tool | Function |
|---|---|
search_manual | Search the built-in user manual (German or English) |
get_manual_section | Fetch the full text of one manual section |
Set up Claude Desktop (one click)
PDF Content Search ships with a one-click installer for Claude Desktop. It takes care of the entire configuration — no need to edit JSON files by hand.
Prerequisite: Claude Desktop is installed (claude.ai/download).
- In PDF Content Search: Settings → Integrations → section “AI assistants (MCP)”
- Click “Set up Claude Desktop”
- Confirm the explanation dialog with “Continue” (macOS asks for one-time permission to write Claude's configuration file)
- In the Finder window, select the already highlighted file
claude_desktop_config.jsonand click “Grant Access” - Restart Claude Desktop; the app offers this directly with “Restart now”
Behind the scenes, the app automatically enables the API server, generates a secure access token, adds the server entry to ~/Library/Application Support/Claude/claude_desktop_config.json, and points to the bundled helper pdf-content-search-mcp inside the app bundle that bridges Claude Desktop's stdio transport with the app's HTTP MCP endpoint. If the app later moves to a different location or the token or port changes, the status line says so; then click “Update Claude Desktop entry”.
Existing entries under mcpServers or other top-level keys are preserved — the installer performs a clean JSON merge. A “Remove from Claude Desktop” button in the same section removes the entry.
Other MCP clients (e.g. Claude Code or custom integrations that support HTTP transport) can still talk to the server directly over HTTP. The app shows the address and both configurations (HTTP and stdio) under “Other apps” with “Set up connection…”.
Use Cases
- Automation scripts: Search documents via REST API and process results further
- AI assistants: Claude or other LLMs can access your documents directly via MCP
- Custom integrations: Client libraries can be generated from the OpenAPI specification