A complete, local PDF workstation for agent clients, packaged to the Agent Plugins 1.0.0 standard. Fill and validate forms, read text and layout with real coordinate geometry, convert to Markdown with evidence-backed tables, compare documents, merge, split, rotate, sign, and inspect accessibility. 43 tools, plus an interactive viewer.
Your files never leave your machine. Every operation runs locally against paths you have explicitly allowed.
codex plugin marketplace add Open-Document-Alliance/pdf-tools-plugin
codex plugin add pdf-tools@open-document-allianceThis repository is a distribution channel. The source lives at Open-Document-Alliance/PDF-Tools. Everything under
plugins/is generated bynpm run build:plugin. Do not edit it here; the next release overwrites it.
This is the part worth reading before you file a bug.
Agent Plugins deliberately defines no user-configuration mechanism. There is no settings screen and no way for a host to ask which folders you trust. A file tool in that position has two options: guess, or refuse. This one refuses.
On first run it creates a config file in your home folder and tells you where. Open it, list the folders you want reachable, and restart:
Absolute paths only. The list replaces any default rather than adding to one, so name every folder you need.
get_allowed_directories will tell you what is currently reachable and which file supplied it, which is the fastest way to check whether a restart actually picked up your edit.
If you configured folders through a host that has its own settings, such as Claude Desktop, that keeps working and takes precedence. This file is for installs where the host offers nothing, which is every Agent Plugins host today.
Why you edit it yourself. We built a tool so you could just ask the assistant to add a folder, and rejected it after review. The server receives a string from whatever is calling it; it cannot tell your words from the agent's, and it cannot tell agreement from refusal. Acting on that would be the constrained process granting itself more room and calling it consent. Your edit is the human action, which is exactly why it stays yours.
Why the boundary works this way at all. Versions before 0.10.0 fell back to Documents, Downloads and Desktop whenever a host supplied no configuration, and nothing in the interface said so. On the plugin path that fallback would have applied to every install. It was removed. The tradeoff is one file on first use, in exchange for a boundary that is always the one you set.
Worth being precise, because "allowed folders" means two different things depending on where you run this.
In an agent that already has shell and filesystem access, such as the Codex CLI, the agent could read your PDF without this extension at all. The boundary there is a guardrail: it keeps a capable agent from wandering, it makes reach explicit and auditable, and it means a mistake stays inside folders you named. It is not a containment barrier against that agent, and nothing in this design pretends otherwise.
In a host where the model has no other filesystem access, such as a plain chat surface, this boundary is the control. Everything the model can reach on your disk, it reaches through this server. That is why the config file is yours to edit and why nothing here can widen it on your behalf.
Neither case is a security sandbox. This server is not a defence against a hostile process on your machine, and it does not claim to be.
Reading and extraction. Text layer extraction, bounded layout with real coordinates, Markdown conversion with tables reconstructed only from geometric or ruled evidence, page analysis, and metadata with typed coverage. Where evidence runs out, the output says so instead of inventing structure.
Forms. Read fields with types and states, fill them, validate against actual PDF Required flags, bulk fill from CSV, save and reuse profiles, extract to CSV.
Documents. Merge, split, rotate, reorder, apply a whole page plan in one pass, fetch a PDF from a URL, compare two documents across semantic, text, structure, form, annotation, metadata and visual channels.
Signatures. Create and place typed or drawn signatures, detect signature and date zones with coordinates, prepare a signing packet. Local visible stamps, not cryptographic signatures, and applying one requires an explicit human intent statement.
Interactive viewer. An MCP Apps component with page navigation, zoom, search, a form field sidebar and a sign mode. It renders in the host, so it travels to any client that supports MCP Apps rather than being tied to one vendor.
Accessibility inspection. Eight catalog-level signals reported as observed, missing or unavailable. It does not establish PDF/UA, WCAG or legal accessibility, and it says so in its own output.
Alpha, and honest about it.
| Codex CLI | Verified. Installs, registers the server, serves tools, and reads a real PDF. |
| ChatGPT desktop app | Verified installed, with its server and skill registered. |
| Cursor, VS Code, GitHub Copilot, Kiro | Not yet verified |
| Interactive viewer on a non-Anthropic host | Not yet observed rendering |
| Claude Desktop | Use the .mcpb instead, see below |
The Agent Plugins specification defines no registry and no install lifecycle, so each client resolves marketplaces its own way. Reports from other clients are welcome in issues on the source repository.
On Claude Desktop, install the .mcpb release instead. It is the better-tested path and it configures folders through the app's own settings, so you skip the config file entirely.
| Path | Purpose |
|---|---|
plugin.json |
Agent Plugins manifest |
mcp.json |
Declares the pdf-tools stdio server, launched through ${PLUGIN_ROOT} |
server/ |
The MCP server |
skills/ |
An evidence-first PDF workflow skill: inspect, plan, authorize, transform, validate, read back |
dist-ui/ |
The interactive viewer, served as an MCP Apps resource |
node_modules/ |
Vendored dependencies |
Dependencies are committed on purpose. Agent Plugins defines no install or build step, so a plugin has to arrive ready to run. Most of the size is @napi-rs/canvas, which carries a native rendering binary for each supported platform so that page rasterization works without a compiler on your machine. Those binaries are version-pinned, so Git stores them once and later releases add only changed server code.
- Local only. Filesystem work and rasterization happen on your machine. There is no PDF service behind this and nothing is uploaded.
- Content you return to the model is processed by whichever host and model you are using, under that provider's terms. That is true of any MCP server.
- Annotation targets are never opened. URLs, destinations and actions found inside a PDF are reported, never followed.
- No OCR. There is no bundled OCR engine. Documents with no text layer are identified as needing vision rather than silently returning nothing.
- Signatures are visible stamps, not cryptographic signatures, and carry no legal weight on their own.
Every call says no folders are allowed. Expected on a fresh install. See the first-run section above, then restart the server so it re-reads the file.
It still refuses after I edited the config. The server reads that file at startup only. Restart it. Check the paths are absolute and the JSON is valid.
A rasterization call fails. Page and region rendering need the native binary for your platform. Every supported platform ships here, so this usually means an incomplete clone. Confirm node_modules/@napi-rs/ contains a skia.*.node file for your platform and architecture.
The clone is large. About 250 MB, most of it those native rendering binaries. This is the cost of a standard with no install step.
git clone https://github.com/Open-Document-Alliance/PDF-Tools.git
cd PDF-Tools && npm ci
npm run build:plugin # -> dist-plugin/pdf-toolsTo serve your own build, put it under plugins/ in any directory and add a marketplace file at .agents/plugins/marketplace.json pointing at it with a path relative to the marketplace root. An absolute path fails with plugin was not found in marketplace, which does not hint at the cause. Then codex plugin marketplace add <that directory>.
MIT, matching PDF Tools. Vendored dependencies keep their own licenses.