Skip to content
Back to search

PDF-Tools

Fill, sign, merge, split, and extract PDFs from Claude Desktop and other MCP hosts. Maintained by the Open Document Alliance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/open-document-alliance--pdf-tools/badge.svg)](/listings/open-document-alliance--pdf-tools)

HTML

<a href="/listings/open-document-alliance--pdf-tools"><img src="/api/listings/open-document-alliance--pdf-tools/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Desktop

1. **[Download the latest `.mcpb` from Releases](https://github.com/Open-Document-Alliance/PDF-Tools/releases/latest)** 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "open-document-alliance",
  3. "owner": {
  4. "name": "Open Document Alliance"
  5. },
  6. "description": "Workflow-only plugins maintained by Open Document Alliance.",
  7. "plugins": [
  8. {
  9. "name": "pdf-tools-workflow",
  10. "source": "./plugins/pdf-tools-workflow",
  11. "description": "A bounded, evidence-first PDF Tools workflow.",
  12. "version": "0.1.0-alpha.1",
  13. "author": {
  14. "name": "Open Document Alliance"
  15. },
  16. "homepage": "https://github.com/Open-Document-Alliance/PDF-Tools",
  17. "repository": "https://github.com/Open-Document-Alliance/PDF-Tools",
  18. "license": "MIT",
  19. "category": "Productivity",
  20. "skills": "./skills/",
  21. "strict": true
  22. }
  23. ]
  24. }
README.md · README · 438 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # PDF Tools for Claude Desktop and Local MCP Hosts
  2. The local PDF workflow for Claude Desktop and MCP hosts: fill, sign, merge,
  3. split, extract, render, and analyze PDFs with local file operations.
  4. Instead of just opening a PDF, PDF Tools lets Claude fetch PDF URLs to your
  5. machine, inspect documents visually, fill forms, save reusable profiles, add
  6. signature/date zones, merge and split files, reorganize pages visually, extract
  7. structured data, and return document content to your chosen MCP host for analysis.
  8. 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.
  9. ## Install
  10. ### Claude Desktop
  11. 1. **[Download the latest `.mcpb` from Releases](https://github.com/Open-Document-Alliance/PDF-Tools/releases/latest)**
  12. 2. Double-click the `.mcpb` file to install it in Claude Desktop
  13. The extension is also available in the Claude Extensions directory.
  14. Claude Desktop settings include an **Allowed PDF Directories** field. By default,
  15. PDF Tools can access `~/Documents`, `~/Downloads`, and `~/Desktop`. Add any other
  16. folder you want Claude to use before asking it to read, fill, sign, merge, or save
  17. PDFs there. Saved profiles and signatures live in the extension's private local
  18. store and do not need to be added manually.
  19. ### Cursor / Other MCP Hosts
  20. ```json
  21. {
  22. "mcpServers": {
  23. "pdf-tools": {
  24. "command": "node",
  25. "args": ["/full/path/to/PDF-Tools/server/index.js"]
  26. }
  27. }
  28. }
  29. ```
  30. ### ChatGPT / Codex Agent Plugin
  31. A fresh Agent Plugin install uses a private PDF Tools workspace. There is no
  32. folder setup step: when the host is allowed to read a file, it can copy the file
  33. into that workspace for PDF Tools to process. PDF Tools itself still refuses
  34. direct paths outside the workspace.
  35. This is a tool boundary, not a confidentiality boundary against the host. If
  36. ChatGPT is set to Full Access, its broader filesystem permission governs what it
  37. can import. Optional direct folder access can be configured separately in the
  38. plugin's `config.json`; a non-empty list replaces the private workspace.
  39. ## Why It's Different
  40. Claude already knows how to read PDFs in limited ways. PDF Tools goes much further:
  41. - **Interactive viewer:** page navigation, zoom, search, fullscreen, text selection, and form-field sidebar
  42. - **Form workflows:** `fill_pdf`, `read_pdf_fields`, `bulk_fill_from_csv`, and reusable profiles
  43. - **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
  44. - **URL-to-PDF workflows:** fetch HTTP(S) PDF links to the local machine when sandboxed web fetches are blocked
  45. - **Page organization:** merge, split, rotate, reorder, and apply full page plans in one pass
  46. - **Extraction and analysis:** page-bounded reads, text search, page/region rendering, CSV export, page-level analysis, metadata, and validation
  47. - **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
  48. - **Local file operations:** PDF Tools reads, renders, edits, and saves files on your machine instead of uploading them to a separate PDF service
  49. - **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
  50. Text, images, and metadata returned by PDF Tools may be processed by Claude or
  51. another MCP host. Your host and model provider's data terms apply to that
  52. content, so the complete workflow is not necessarily zero egress.
  53. ## What You Can Do
  54. ### Interactive PDF Viewer
  55. - View PDFs with page navigation, zoom, search, and fullscreen
  56. - Select and copy text directly from pages
  57. - See form fields in a sidebar with fill status
  58. - Use visual page management to reorder, rotate, and remove pages before saving a new copy
  59. ### URL-to-PDF Workflows
  60. - Download PDFs from HTTP(S) URLs to your local machine
  61. - Open downloaded PDFs immediately in the viewer for fill, sign, page management, extraction, or analysis
  62. - Use the local MCP host for cases where Claude's normal web/proxy fetch path cannot retrieve the PDF
  63. - Keep downloaded PDFs inside user-approved local directories
  64. ### Forms and Reusable Profiles
  65. - Fill W-9s, 1099s, rental applications, waivers, and any fillable PDF
  66. - Save personal or business details as reusable profiles
  67. - List, load, and apply saved profiles so repeated forms take seconds instead of minutes
  68. - Bulk fill many PDFs from CSV data and validate required fields before submission
  69. ### Sign Mode and Local Signatures
  70. - Detect likely signature, initials, printed-name, and date zones with model-readable coordinates
  71. - Switch to the viewer's Sign tab to place signatures, dates, or text on detected zones
  72. - Draw or reuse saved local signatures
  73. - Inspect a region, preview it, and turn it into a typed signing zone when automatic detection is not enough
  74. - 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
  75. - Keep signing edits local, with active-document tracking and backup behavior for same-file mutations
  76. - 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
  77. - 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
  78. ### Optional Lumin e-signing
  79. Lumin e-signing is an explicit external workflow. The rest of PDF Tools stays
  80. local-first. PDF Tools contacts Lumin only when a Lumin tool is called. Sending
  81. requires a provider-ready `prepare_signing_packet` receipt, a local preview, a
  82. connected Lumin session, and the user's fresh verbatim confirmation. The
  83. prepared PDF plus listed names and email addresses then leave the device and are
  84. handled by Lumin.
  85. PDF Tools can validate the exact confirmation text and its freshness, but it
  86. cannot independently prove who typed it. The MCP host must present the
  87. destructive tool action, and the agent must pass only the user's actual words
  88. and time. Agents must never fabricate either value.
  89. This is currently a maintainer-configured integration, not a fully qualified
  90. one-click signup experience. An ordinary user should not need to create a
  91. developer app. If signing is not configured, ask the installation's maintainer;
  92. creating a personal Lumin account alone does not enable the integration.
  93. For password-protected local PDFs, ask PDF Tools to unlock the document. Enter
  94. the password in its private local browser window, never in chat. Access is
  95. limited to the exact file and the current server session, expires after ten
  96. minutes, and can be ended with `lock_pdf`. Unlocking preserves the document's
  97. permissions and encryption; it does not enable otherwise unsupported encrypted
  98. rendering or comparison. See [private password entry](https://github.com/Open-Document-Alliance/PDF-Tools/blob/abaf94096c7e99328d40407506adff5b16584d1d/docs/ENCRYPTED_PDF_CREDENTIAL_PROPOSAL.md).
  99. Once configured, ask PDF Tools to connect Lumin. Sign in and approve access in
  100. the browser, never by sharing passwords or callback URLs in chat. If you need
  101. an account, create it on Lumin's website. If signup does not return to the
  102. connection before it expires, start the connection again. Connecting does not
  103. upload a PDF, send an invitation, or approve a signature. After reconnecting,
  104. check an existing request rather than sending it again.
  105. For maintainers: configure a public OAuth client ID in the extension's **Lumin OAuth Client ID**
  106. setting. Other stdio hosts may set `LUMIN_OAUTH_CLIENT_ID`; Agent Plugin users
  107. may set `luminOAuthClientId` in the plugin's private `config.json`. Register the
  108. exact redirect URI `http://127.0.0.1/callback`. The OAuth access token stays only
  109. in the running PDF Tools process. It is not returned, logged, or written to
  110. disk, and a restart requires connecting again.
  111. The create call is one-shot and has no automatic retry. If the provider outcome
  112. is uncertain, PDF Tools preserves that uncertainty and will not create another
  113. request under the same authority. Status polling is the current desktop path.
  114. Lumin app webhooks require a private server app and are not part of this public
  115. PKCE workflow. The durable signing-operation store currently supports macOS and
  116. Linux. The public Lumin workflow fails closed on Windows until a reviewed
  117. ACL-aware state adapter exists.
  118. Lumin also provides its own hosted MCP and an API-key-based local extension.
  119. These are separate connections, not automatically installed, authenticated, or
  120. invoked by PDF Tools. See [Lumin onboarding and integration boundaries](docs/LUMIN_ONBOARDING.md)
  121. for the capability comparison, first-time-user limitations, and attribution
  122. proposal. No signup tracking or analytics reporting is enabled by this work.
  123. ### Page Organization Tools
  124. - Merge multiple PDFs into one document
  125. - Split PDFs by exact page ranges or regular intervals
  126. - Rotate and reorder pages
  127. - Apply a full page plan in one pass to reorder, rotate, and delete pages while preserving the original
  128. ### Extraction and Analysis
  129. - Read existing PDF text layers for summarization, question answering, and research workflows
  130. - Extract structured data to CSV
  131. - Inspect page-level details like orientation, text presence, images, and likely blank pages
  132. - Review source-bound page geometry, bounded metadata, form widgets, ordinary annotations, and file identity
  133. - Inspect exactly eight shallow catalog-level accessibility signals with explicit missing or unavailable states and required human review
  134. - 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
  135. See [Verified extraction workspaces](docs/VERIFIED_EXTRACTION.md) for the
  136. complete lifecycle, supported methods, privacy boundary, and current limits.
  137. PDF Tools does not currently bundle an OCR engine. Text reads use the PDF.js
  138. text layer. If the selected `read_pdf_content` result contains no text, the tool
  139. may return a rendered image of page 1 for vision-capable host/model inspection.
  140. Page and region rendering produces raster images, not recognized text. A mixed
  141. text/raster PDF, or raster pages after page 1, may therefore contain content the
  142. broad text read does not recognize. Optional local OCR adapters and resumable
  143. proposal jobs require a separately installed engine and explicit configuration;
  144. their output remains unverified until reviewed. See [Optional local OCR](docs/LOCAL_OCR.md).
  145. `get_pdf_info` binds these observations to the exact race-aware source
  146. SHA-256, keeps widget annotations separate from ordinary annotations, and
  147. returns link or action targets only as inert values. Page and region renders
  148. report page geometry, coordinate spaces, renderer policy, the PNG SHA-256,
  149. and raw RGBA SHA-256 availability.
  150. `inspect_pdf_accessibility` is a bounded structural-review screen for an
  151. unencrypted local PDF. It does not run veraPDF, assess tag semantics or
  152. assistive-technology behavior, or establish PDF/UA, WCAG, certification,
  153. legal, or document-accessibility conclusions.
  154. Region-render inputs are top-left PDF.js viewport points after CropBox,
  155. rotation, and UserUnit. They are not MediaBox-relative signing-zone
  156. coordinates. The macOS Quick Look fallback renders whole pages and regions in
  157. that same view and reports raw pixels unavailable.
  158. ## Great Fit For
  159. - Researchers reviewing papers and reports
  160. - Operators processing forms and back-office PDFs
  161. - Lawyers organizing contracts and comparing versions
  162. - Accountants handling tax documents
  163. - Anyone who wants local PDF file operations in Claude without a separate PDF upload service
  164. ## Example Prompts
  165. ### View and Inspect
  166. - "Open my W-9 and show me the fields"
  167. - "Display the contract PDF in my Documents folder"
  168. - "Search this report for every mention of indemnification"
  169. - "Download this PDF URL locally, open it, and tell me what needs to be filled out"
  170. ### Fill Forms
  171. - "Fill this W-9 with my business info: Company Name LLC, 123 Main St, Tax ID 12-3456789"
  172. - "Use my work profile to fill this application"
  173. - "Save this data as a reusable profile called advisor-office"
  174. ### Sign and Date
  175. - "Find every place this PDF needs a signature or date"
  176. - "Open Sign mode so I can draw and place my signature"
  177. - "Add sign-here and date boxes to this completed form"
  178. - "Inspect the signature block on page 5 and create a custom signing zone there"
  179. ### Organize Pages
  180. - "Merge these three contracts into one PDF"
  181. - "Split this report every 10 pages"
  182. - "Rotate page 3 by 90 degrees"
  183. - "Open Manage Pages so I can reorder and delete pages visually"
  184. ### Analyze and Extract
  185. - "Summarize this research paper"
  186. - "Read the available text from this invoice and tell me which pages need visual inspection"
  187. - "Render page 1 of this scanned invoice so you can inspect it visually"
  188. - "Render just the signature block on page 3 so you can inspect it visually"
  189. - "Read pages 8 through 10 of this contract"
  190. - "Search this PDF for every mention of governing law"
  191. - "Convert pages 1 through 6 of this PDF to Markdown and tell me about any coverage gaps"
  192. - "Export all the filled fields from these PDFs into a CSV"
  193. - "Analyze this PDF for blank pages and sideways pages"
  194. ## Core Tools
  195. This list is complete for default discovery. Three tools, `read_pdf_bytes`,
  196. `open_pdf_workspace`, and `import_host_pdf`, are app-only and are not packed into
  197. the `.mcpb` manifest that ordinary model workflows discover.
  198. ### Viewer and Reading
  199. - `unlock_pdf` (opens private local password entry, outside chat)
  200. - `get_pdf_unlock_status` (checks the current session's unlock state)
  201. - `lock_pdf` (forgets the current session's credential)
  202. - `display_pdf`
  203. - `fetch_pdf_from_url`
  204. - `list_pdfs`
  205. - `read_pdf_content`
  206. - `read_pdf_pages`
  207. - `read_pdf_layout`
  208. - `convert_pdf_to_markdown` (reconstructs evidence-backed tables and source-validated external http or https links; unsupported, ambiguous, internal, and action links stay escaped text reported as typed gaps)
  209. - `verify_table_proposal` (checks a suggested table against the original PDF and returns it only when the text and layout match the document; unclear tables stay unconverted for review)
  210. - `render_pdf_page`
  211. - `render_pdf_region`
  212. - `search_pdf_text`
  213. - `get_pdf_resource_uri`
  214. ### Forms and Profiles
  215. - `read_pdf_fields`
  216. - `fill_pdf`
  217. - `bulk_fill_from_csv`
  218. - `save_profile`
  219. - `load_profile`
  220. - `list_profiles`
  221. - `fill_with_profile`
  222. - `validate_pdf`
  223. ### Signatures
  224. - `detect_signature_zones`
  225. - `add_signature_field`
  226. - `prepare_signing_packet`
  227. - `start_lumin_authorization`
  228. - `finish_lumin_authorization`
  229. - `prepare_lumin_request`
  230. - `send_lumin_request`
  231. - `check_lumin_status`
  232. - `download_lumin_artifact`
  233. - `create_signature`
  234. - `list_signatures`
  235. - `load_signature`
  236. - `apply_signature`
  237. - `apply_text`
  238. ### Organization and Page Management
  239. - `merge_pdfs`
  240. - `split_pdf`
  241. - `rotate_pdf_pages`
  242. - `reorder_pdf_pages`
  243. - `apply_page_plan`
  244. ### Extraction and Analysis
  245. - `extract_to_csv`
  246. - `compare_pdfs`
  247. - `get_pdf_identity`
  248. - `get_pdf_info`
  249. - `inspect_pdf_accessibility`
  250. - `get_page_analysis`
  251. - `create_extraction_workspace`
  252. - `inspect_extraction_state`
  253. - `read_extraction_workspace`
  254. - `read_extraction_chunk`
  255. - `submit_extraction_proposal`
  256. - `verify_extraction_proposal`
  257. - `verify_extraction_batch`
  258. - `review_extraction_workspace`
  259. - `delete_extraction_workspace`
  260. The [Evidence view](docs/EVIDENCE_REVIEW.md) connects extraction values to
  261. source text, page coverage, and correction history. Optional local OCR and
  262. resumable page jobs require [explicit adapter setup](docs/LOCAL_OCR.md).
  263. ### Active Document and Host Helpers
  264. - `open_pdf_workspace` (app-only starting screen; no PDF or folder access)
  265. - `import_host_pdf` (app-only bounded byte import into the already-permitted private workspace; no path fetching or host-file replacement)
  266. - `get_active_document`
  267. - `set_active_document`
  268. - `get_allowed_directories`
  269. - `read_pdf_bytes`
  270. - `reveal_in_finder`
  271. ## Build From Source
  272. ```bash
  273. git clone https://github.com/Open-Document-Alliance/PDF-Tools
  274. cd PDF-Tools
  275. npm ci
  276. npm run build:mcpb
  277. ```
  278. ## Development
  279. <details>
  280. <summary>Development and maintainer details</summary>
  281. ### Project Structure
  282. ```text
  283. PDF-Tools/
  284. ├── server/index.js # MCP server entry point
  285. ├── server/helpers.js # Shared helper functions
  286. ├── ui/ # Interactive viewer source (TypeScript)
  287. ├── dist-ui/ # Built viewer (single-file HTML)
  288. ├── test/ # Unit tests (Vitest)
  289. ├── manifest.json # Extension metadata
  290. ├── manifest.mcpb.json # MCPB packaging manifest
  291. ├── package-for-friend.js # Share-bundle packaging script
  292. └── docs/ # Maintainer and release docs
  293. ```
  294. ### Common Commands
  295. ```bash
  296. npm install
  297. npm run dev:ui
  298. npm run smoke:ui-dev
  299. npm run smoke:ui-sign
  300. npm run smoke:ui-inspect
  301. npm run smoke:ui-preview-zone
  302. npm run smoke:ui-draw
  303. npm run smoke:mcpb -- pdf-toolkit-mcp.mcpb
  304. npm run build:ui
  305. npm run build:mcpb
  306. npm test
  307. npm run test:node-native
  308. npm run test:all
  309. node server/index.js
  310. node package-for-friend.js
  311. ```
  312. `npm test` runs the Vitest partition. Release qualification uses
  313. `npm run test:all` so the explicitly classified Node native-test suites cannot
  314. be silently omitted.
  315. ### Viewer Dev Mode
  316. `npm run dev:ui` starts the Vite viewer with a mocked ext-apps host and a real local MCP subprocess behind `/__dev__/tool`.
  317. - Default URL: `http://127.0.0.1:5173/?pdf_path=example-fw9.pdf`
  318. - You can point at another file with `?pdf_path=/absolute/path/to/file.pdf`
  319. - The dev bridge is serve-only; `npm run build:ui` still produces the production single-file viewer for packaging
  320. - `npm run smoke:ui-dev` starts the dev server on a throwaway port, verifies the HTML loads, and round-trips a real `display_pdf` tool call through `/__dev__/tool`
  321. - `npm run smoke:ui-sign` boots the dev server, opens a real browser session with `agent-browser`, switches to sign mode, and verifies a sign-panel interaction opens a signing modal
  322. - `npm run smoke:ui-inspect` boots the dev server, opens a real browser session with `agent-browser`, switches to sign mode, arms inspect-region, drags a rectangle, and verifies the region preview modal opens
  323. - `npm run smoke:ui-preview-zone` boots the dev server, opens a real browser session, drives inspect-region, creates a zone from the preview modal, and verifies the sign modal opens on that new custom zone
  324. - `npm run smoke:ui-draw` boots the dev server, opens the draw-signature modal in a real browser session, sketches a small stroke, fills the save fields, and verifies the modal closes after saving
  325. ### Maintainer Docs
  326. - `docs/MAINTAINERS.md`: architecture and operations
  327. - `docs/RELEASE.md`: release checklist
  328. - `docs/SUPPORT.md`: issue triage
  329. </details>
  330. ## Upstream Dependencies
  331. - MCP spec: https://github.com/modelcontextprotocol
  332. - MCPB CLI: https://github.com/modelcontextprotocol/mcpb
  333. - MCP Apps: https://github.com/modelcontextprotocol/ext-apps
  334. - SDK: `@modelcontextprotocol/sdk`
  335. ## License
  336. MIT
  337. ### Third-party notices
  338. The MCPB and the share ZIP both carry a vendored QPDF WebAssembly runtime at
  339. `vendor/qpdf-wasm/runtime/`. No tool loads it yet; it is packaged ahead of the
  340. integration that will use it. qpdf is Apache-2.0, and the complete notice set
  341. (qpdf, zlib, libjpeg-turbo, the Emscripten generated runtime, musl,
  342. compiler-rt, libc++, libc++abi and libunwind) ships beside it in
  343. `vendor/qpdf-wasm/runtime/licenses/`, bound to its SHA-256 hashes by
  344. `licenses/manifest.json`. The npm dependencies keep their own licences inside
  345. `node_modules/`, including the PDF.js, Foxit and Liberation font notices.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.