TruePath PDF 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 20 or newer.

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 preserved
• flatten — bake filled forms / annotations into the page stream
• sign — visible signature placement, signed-PDF write
• compress — recompress images / streams to shrink file size
• annotate — programmatic highlight / underline / sticky-note
• autocrop — detect content bounds and crop margins
• batch — apply any tool across a glob of files
• ocr — 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 — MIT
• pdfjs-dist — Apache 2.0
• pdf-lib — MIT
• @napi-rs/canvas — MIT
• zod — 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)