pdf-tools

PDF Tools for Claude Desktop and Local MCP Hosts

The local PDF workflow for Claude Desktop and MCP hosts: fill, sign, merge, split, extract, render, and analyze PDFs with local file operations.

Instead of just opening a PDF, PDF Tools lets Claude fetch PDF URLs to your machine, inspect documents visually, fill forms, save reusable profiles, add signature/date zones, merge and split files, reorganize pages visually, extract structured data, and return document content to your chosen MCP host for analysis.

This package targets Claude Desktop and other local MCP hosts today. It does not yet include a remote connector for Claude Cowork / web-hosted Claude.

Install

Claude Desktop

1. Download the latest .mcpb from Releases
2. Double-click the .mcpb file to install it in Claude Desktop

The extension is also available in the Claude Extensions directory.

Claude Desktop settings include an Allowed PDF Directories field. By default, PDF Tools can access ~/Documents, ~/Downloads, and ~/Desktop. Add any other folder you want Claude to use before asking it to read, fill, sign, merge, or save PDFs there. Saved profiles and signatures live in the extension's private local store and do not need to be added manually.

Cursor / Other MCP Hosts

{
  "mcpServers": {
    "pdf-tools": {
      "command": "node",
      "args": ["/full/path/to/PDF-Tools/server/index.js"]
    }
  }
}

ChatGPT / Codex Agent Plugin

A fresh Agent Plugin install uses a private PDF Tools workspace. There is no folder setup step: when the host is allowed to read a file, it can copy the file into that workspace for PDF Tools to process. PDF Tools itself still refuses direct paths outside the workspace.

This is a tool boundary, not a confidentiality boundary against the host. If ChatGPT is set to Full Access, its broader filesystem permission governs what it can import. Optional direct folder access can be configured separately in the plugin's config.json; a non-empty list replaces the private workspace.

Why It's Different

Claude already knows how to read PDFs in limited ways. PDF Tools goes much further:

• Interactive viewer: page navigation, zoom, search, fullscreen, text selection, and form-field sidebar
• Form workflows: fill_pdf, read_pdf_fields, bulk_fill_from_csv, and reusable profiles
• Sign mode: signature/date zone detection, saved or drawn local signatures, text stamping, inspect-region, preview-to-zone flows, and optional consent-gated Lumin e-signing
• URL-to-PDF workflows: fetch HTTP(S) PDF links to the local machine when sandboxed web fetches are blocked
• Page organization: merge, split, rotate, reorder, and apply full page plans in one pass
• Extraction and analysis: page-bounded reads, text search, page/region rendering, CSV export, page-level analysis, metadata, and validation
• Verified extraction workspaces: bind a PDF and JSON Schema, inspect source chunks, submit cited leaf proposals, and retain deterministic replay results without a model inside the MCP server
• Local file operations: PDF Tools reads, renders, edits, and saves files on your machine instead of uploading them to a separate PDF service
• Scoped file operations: PDF Tools directly reads and writes only its active folders; a host with broader filesystem permission may import files into the private plugin workspace

Text, images, and metadata returned by PDF Tools may be processed by Claude or another MCP host. Your host and model provider's data terms apply to that content, so the complete workflow is not necessarily zero egress.

What You Can Do

Interactive PDF Viewer

• View PDFs with page navigation, zoom, search, and fullscreen
• Select and copy text directly from pages
• See form fields in a sidebar with fill status
• Use visual page management to reorder, rotate, and remove pages before saving a new copy

URL-to-PDF Workflows

• Download PDFs from HTTP(S) URLs to your local machine
• Open downloaded PDFs immediately in the viewer for fill, sign, page management, extraction, or analysis
• Use the local MCP host for cases where Claude's normal web/proxy fetch path cannot retrieve the PDF
• Keep downloaded PDFs inside user-approved local directories

Forms and Reusable Profiles

• Fill W-9s, 1099s, rental applications, waivers, and any fillable PDF
• Save personal or business details as reusable profiles
• List, load, and apply saved profiles so repeated forms take seconds instead of minutes
• Bulk fill many PDFs from CSV data and validate required fields before submission

Sign Mode and Local Signatures

• Detect likely signature, initials, printed-name, and date zones with model-readable coordinates
• Switch to the viewer's Sign tab to place signatures, dates, or text on detected zones
• Draw or reuse saved local signatures
• Inspect a region, preview it, and turn it into a typed signing zone when automatic detection is not enough
• Prepare a provider-neutral handoff receipt that binds the exact local input/output, typed zones, participant roles, page geometry, and unresolved inputs without contacting a signing provider
• Keep signing edits local, with active-document tracking and backup behavior for same-file mutations
• Optionally connect a Lumin account with browser-based PKCE, preview the exact recipients and disclosure locally, and send the prepared PDF only after the user confirms the exact sending statement
• Check an existing Lumin request by polling and download an agreement or completion certificate without exposing the temporary signed URL or replacing an existing local file

Optional Lumin e-signing

Lumin e-signing is an explicit external workflow. The rest of PDF Tools stays local-first. PDF Tools contacts Lumin only when a Lumin tool is called. Sending requires a provider-ready prepare_signing_packet receipt, a local preview, a connected Lumin session, and the user's fresh verbatim confirmation. The prepared PDF plus listed names and email addresses then leave the device and are handled by Lumin.

PDF Tools can validate the exact confirmation text and its freshness, but it cannot independently prove who typed it. The MCP host must present the destructive tool action, and the agent must pass only the user's actual words and time. Agents must never fabricate either value.

This is currently a maintainer-configured integration, not a fully qualified one-click signup experience. An ordinary user should not need to create a developer app. If signing is not configured, ask the installation's maintainer; creating a personal Lumin account alone does not enable the integration.

For password-protected local PDFs, ask PDF Tools to unlock the document. Enter the password in its private local browser window, never in chat. Access is limited to the exact file and the current server session, expires after ten minutes, and can be ended with lock_pdf. Unlocking preserves the document's permissions and encryption; it does not enable otherwise unsupported encrypted rendering or comparison. See private password entry.

Once configured, ask PDF Tools to connect Lumin. Sign in and approve access in the browser, never by sharing passwords or callback URLs in chat. If you need an account, create it on Lumin's website. If signup does not return to the connection before it expires, start the connection again. Connecting does not upload a PDF, send an invitation, or approve a signature. After reconnecting, check an existing request rather than sending it again.

For maintainers: configure a public OAuth client ID in the extension's Lumin OAuth Client ID setting. Other stdio hosts may set LUMIN_OAUTH_CLIENT_ID; Agent Plugin users may set luminOAuthClientId in the plugin's private config.json. Register the exact redirect URI http://127.0.0.1/callback. The OAuth access token stays only in the running PDF Tools process. It is not returned, logged, or written to disk, and a restart requires connecting again.

The create call is one-shot and has no automatic retry. If the provider outcome is uncertain, PDF Tools preserves that uncertainty and will not create another request under the same authority. Status polling is the current desktop path. Lumin app webhooks require a private server app and are not part of this public PKCE workflow. The durable signing-operation store currently supports macOS and Linux. The public Lumin workflow fails closed on Windows until a reviewed ACL-aware state adapter exists.

Lumin also provides its own hosted MCP and an API-key-based local extension. These are separate connections, not automatically installed, authenticated, or invoked by PDF Tools. See Lumin onboarding and integration boundaries for the capability comparison, first-time-user limitations, and attribution proposal. No signup tracking or analytics reporting is enabled by this work.

Page Organization Tools

• Merge multiple PDFs into one document
• Split PDFs by exact page ranges or regular intervals
• Rotate and reorder pages
• Apply a full page plan in one pass to reorder, rotate, and delete pages while preserving the original

Extraction and Analysis

• Read existing PDF text layers for summarization, question answering, and research workflows
• Extract structured data to CSV
• Inspect page-level details like orientation, text presence, images, and likely blank pages
• Review source-bound page geometry, bounded metadata, form widgets, ordinary annotations, and file identity
• Inspect exactly eight shallow catalog-level accessibility signals with explicit missing or unavailable states and required human review
• Build a private schema-bound extraction workspace, cite source chunks, and retain exact, computed, ambiguous, unverified, or failed results without numeric confidence; absence declarations remain unverified and uncertain results allow append-only correction

See Verified extraction workspaces for the complete lifecycle, supported methods, privacy boundary, and current limits.

PDF Tools does not currently bundle an OCR engine. Text reads use the PDF.js text layer. If the selected read_pdf_content result contains no text, the tool may return a rendered image of page 1 for vision-capable host/model inspection. Page and region rendering produces raster images, not recognized text. A mixed text/raster PDF, or raster pages after page 1, may therefore contain content the broad text read does not recognize. Optional local OCR adapters and resumable proposal jobs require a separately installed engine and explicit configuration; their output remains unverified until reviewed. See Optional local OCR.

get_pdf_info binds these observations to the exact race-aware source SHA-256, keeps widget annotations separate from ordinary annotations, and returns link or action targets only as inert values. Page and region renders report page geometry, coordinate spaces, renderer policy, the PNG SHA-256, and raw RGBA SHA-256 availability.

inspect_pdf_accessibility is a bounded structural-review screen for an unencrypted local PDF. It does not run veraPDF, assess tag semantics or assistive-technology behavior, or establish PDF/UA, WCAG, certification, legal, or document-accessibility conclusions.

Region-render inputs are top-left PDF.js viewport points after CropBox, rotation, and UserUnit. They are not MediaBox-relative signing-zone coordinates. The macOS Quick Look fallback renders whole pages and regions in that same view and reports raw pixels unavailable.

Great Fit For

• Researchers reviewing papers and reports
• Operators processing forms and back-office PDFs