TruePath PDF — MCP server
Let your AI process PDFs locally. Files never leave your Mac.
@truepathpdf/mcp-server is a Model Context Protocol server that lets Claude, Cursor, and any other MCP-aware client read and process PDF files on your machine — without uploading them anywhere.
Built and maintained by Joy Truepath Pte. Ltd., the team behind the TruePath PDF Mac app.
Status
v0.3 — free tier complete (9 of 9 tools). Read + edit + rasterise + GUI handoff: get_info, extract_text, search, split, merge, pages, to_images, extract_images, open_in_truepath. The full Pro tier (redact, fill_form, flatten, sign, compress, annotate, autocrop, batch, ocr) lands behind an Ed25519 license key in v0.4.
open_in_truepath requires the TruePath PDF Mac app v1.0.1 or newer (the truepath:// handler is added in 1.0.1; the v1.0.0 build does not register it).
Privacy
- 100% local. The MCP server runs on your machine and never talks to a network.
- No telemetry, no analytics, no phone-home.
- Free tools work fully offline, forever, with no key.
- Pro tools (coming soon) are gated by an offline Ed25519 license check — still no network call at use time.
Install
# npx — no install required
npx -y @truepathpdf/mcp-server
# or install globally
npm install -g @truepathpdf/mcp-server
truepath-pdf-mcp
Requires Node.js 22.13 or newer (PDF.js 6 needs it).
Hook up to Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"truepath-pdf": {
"command": "npx",
"args": ["-y", "@truepathpdf/mcp-server"]
}
}
}
Restart Claude Desktop. The truepath-pdf tools appear in the tool tray.
Tools (v0.2)
get_info
Page count, first-page size (with an allSameSize flag), encryption status, and embedded PDF metadata (title, author, dates, producer, format version).
{ "path": "/Users/you/Documents/report.pdf" }
extract_text
Plain-text extraction. Optional 1-based page range ("3", "1-5", "1,3,5-7"). Output is grouped by page with ===== Page N ===== markers so the model can cite the right page.
{ "path": "/Users/you/Documents/report.pdf", "pages": "1-3" }
search
Substring search across the whole document. Returns each hit's page, offset within the page, and a snippet of surrounding text. Use for grep-style discovery before a heavier extract_text.
{ "path": "/Users/you/Documents/report.pdf", "query": "revenue", "contextChars": 80 }
split
Split one PDF into N by page ranges. Each range becomes one output file.
{ "path": "/in.pdf", "ranges": ["1-3", "4-7", "8"], "outputDir": "/out" }
merge
Combine two or more PDFs into one, in the given order.
{ "paths": ["/a.pdf", "/b.pdf", "/c.pdf"], "outputPath": "/out/merged.pdf" }
pages
Delete, rotate, and reorder pages in one pass. delete is applied first (page numbers in rotate refer to the source PDF); reorder is applied to the survivors.
{
"path": "/in.pdf",
"outputPath": "/out/edited.pdf",
"delete": "2,5",
"rotate": [{ "page": 1, "degrees": 90 }],
"reorder": [3, 1, 2]
}
to_images
Rasterise PDF pages as PNG or JPG at a chosen DPI. Common DPIs: 96 (screen), 150 (print preview), 300 (print).
{ "path": "/in.pdf", "outputDir": "/out", "pages": "1-5", "dpi": 150, "format": "png" }
extract_images
Pull embedded images out of a PDF and write each as a PNG. Reports any images skipped because of unsupported pixel layouts (CMYK, palettized, etc).
{ "path": "/in.pdf", "outputDir": "/out" }
open_in_truepath
Hand a local PDF to the TruePath PDF Mac app via truepath://open?path=…. Fire-and-forget: macOS launches (or routes to) the app, the URL handler opens the PDF. Use this after reading / analyzing in MCP to drop the user into the GUI for annotation, signing, redaction, etc.
{ "path": "/Users/you/Documents/report.pdf" }
Optional scheme param for re-branded engine builds (default truepath; the Yochen core build uses yochenpdf).
If the app isn't installed (no truepath:// handler registered — the app is absent or older than v1.0.1), the tool doesn't error. It returns handedOff: false with a one-line pointer to the TruePath PDF download so you can install it and retry. (Only for the default truepath scheme; a custom scheme gets a plain failure.)
Roadmap
Pro tier (v0.4, Ed25519 license key, offline verify)
redact— text-preserving redaction via PDFium (the same engine the Mac app uses; the words are removed from the file, not just covered)fill_form— fill AcroForm fields, save with values preservedflatten— bake filled forms / annotations into the page streamsign— visible signature placement, signed-PDF writecompress— recompress images / streams to shrink file sizeannotate— programmatic highlight / underline / sticky-noteautocrop— detect content bounds and crop marginsbatch— apply any tool across a glob of filesocr— Apple Vision OCR (Mac only, on-device, CJK-strong)
A buy-once Pro key will be available via Lemon Squeezy at launch (target: USD 29, includes 12 months of updates). Owners of the TruePath PDF Mac app will be able to redeem their App Store receipt for a Pro MCP key via an in-app button.
License
MIT for the MCP shell. Transitive dependencies:
@modelcontextprotocol/sdk— MITpdfjs-dist— Apache 2.0pdf-lib— MIT@napi-rs/canvas— MITzod— MIT
Pro tier will additionally bundle a prebuilt PDFium library (BSD/Apache, the same one used by Chrome).
Contact
- Issues: https://github.com/JoyTruepath/truepath-pdf-mcp/issues
- Mail: [email protected]
- Joy Truepath Pte. Ltd., Singapore (UEN 202205336E)