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: Cloud processing status and control
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
In release builds, a Bearer token is required. Configure it under Settings → Integrations → API Server. The /health and /docs endpoints are accessible without authentication.
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. 22 tools are available:
| 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, 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 |
| License | get_license_status, refresh_license |
MCP uses the same Bearer token authentication as the REST API.
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 |
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 |
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 |
|---|---|
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 |
ui_navigate | Navigate within the document list |
ui_select_document | Select a document in the list |
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 by key (requires confirmation) |
deactivate_license | Deactivate the current license (requires confirmation) |
request_trial | Start a trial period (requires confirmation) |
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 |
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 “MCP”
- Click “Set up Claude Desktop”
- Confirm the explanation dialog with “Continue” (macOS asks for one-time permission to write Claude's configuration file)
- Restart Claude Desktop
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 installs a small helper binary (pdf-content-search-mcp) inside the app bundle that bridges Claude Desktop's stdio transport with the app's HTTP MCP endpoint.
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/SSE transport) can still talk to the server directly over HTTP. The app provides both configuration snippets (HTTP and stdio) via the “Configuration snippet for other MCP clients…” button.
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