{
  "markdown": "# TruePath PDF — MCP server\n\n**Let your AI process PDFs locally. Files never leave your Mac.**\n\n`@truepathpdf/mcp-server` is a [Model Context Protocol](https://modelcontextprotocol.io/) server that lets Claude, Cursor, and any other MCP-aware client read and process PDF files on your machine — without uploading them anywhere.\n\nBuilt and maintained by [Joy Truepath Pte. Ltd.](https://joytruepath.com/?utm_source=github&utm_medium=referral&utm_campaign=2026-07-pdf-readme), the team behind the [**TruePath PDF**](https://joytruepath.com/truepath-pdf?utm_source=github&utm_medium=referral&utm_campaign=2026-07-pdf-readme) Mac app.\n\n## Status\n\n**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.\n\n`open_in_truepath` requires the [TruePath PDF Mac app](https://joytruepath.com/truepath-pdf?utm_source=github&utm_medium=referral&utm_campaign=2026-07-pdf-readme) **v1.0.1 or newer** (the `truepath://` handler is added in 1.0.1; the v1.0.0 build does not register it).\n\n## Privacy\n\n- 100% local. The MCP server runs on your machine and never talks to a network.\n- No telemetry, no analytics, no phone-home.\n- Free tools work fully offline, forever, with no key.\n- Pro tools (coming soon) are gated by an offline Ed25519 license check — still no network call at use time.\n\n## Install\n\n```bash\n# npx — no install required\nnpx -y @truepathpdf/mcp-server\n\n# or install globally\nnpm install -g @truepathpdf/mcp-server\ntruepath-pdf-mcp\n```\n\nRequires Node.js 20 or newer.\n\n## Hook up to Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"truepath-pdf\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@truepathpdf/mcp-server\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The `truepath-pdf` tools appear in the tool tray.\n\n## Tools (v0.2)\n\n### `get_info`\nPage count, first-page size (with an `allSameSize` flag), encryption status, and embedded PDF metadata (title, author, dates, producer, format version).\n```\n{ \"path\": \"/Users/you/Documents/report.pdf\" }\n```\n\n### `extract_text`\nPlain-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.\n```\n{ \"path\": \"/Users/you/Documents/report.pdf\", \"pages\": \"1-3\" }\n```\n\n### `search`\nSubstring 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`.\n```\n{ \"path\": \"/Users/you/Documents/report.pdf\", \"query\": \"revenue\", \"contextChars\": 80 }\n```\n\n### `split`\nSplit one PDF into N by page ranges. Each range becomes one output file.\n```\n{ \"path\": \"/in.pdf\", \"ranges\": [\"1-3\", \"4-7\", \"8\"], \"outputDir\": \"/out\" }\n```\n\n### `merge`\nCombine two or more PDFs into one, in the given order.\n```\n{ \"paths\": [\"/a.pdf\", \"/b.pdf\", \"/c.pdf\"], \"outputPath\": \"/out/merged.pdf\" }\n```\n\n### `pages`\nDelete, 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.\n```\n{\n  \"path\": \"/in.pdf\",\n  \"outputPath\": \"/out/edited.pdf\",\n  \"delete\": \"2,5\",\n  \"rotate\": [{ \"page\": 1, \"degrees\": 90 }],\n  \"reorder\": [3, 1, 2]\n}\n```\n\n### `to_images`\nRasterise PDF pages as PNG or JPG at a chosen DPI. Common DPIs: `96` (screen), `150` (print preview), `300` (print).\n```\n{ \"path\": \"/in.pdf\", \"outputDir\": \"/out\", \"pages\": \"1-5\", \"dpi\": 150, \"format\": \"png\" }\n```\n\n### `extract_images`\nPull embedded images out of a PDF and write each as a PNG. Reports any images skipped because of unsupported pixel layouts (CMYK, palettized, etc).\n```\n{ \"path\": \"/in.pdf\", \"outputDir\": \"/out\" }\n```\n\n### `open_in_truepath`\nHand 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.\n```\n{ \"path\": \"/Users/you/Documents/report.pdf\" }\n```\nOptional `scheme` param for re-branded engine builds (default `truepath`; the Yochen core build uses `yochenpdf`).\n\nIf 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](https://joytruepath.com/truepath-pdf) download so you can install it and retry. (Only for the default `truepath` scheme; a custom `scheme` gets a plain failure.)\n\n## Roadmap\n\n### Pro tier (v0.4, Ed25519 license key, offline verify)\n- `redact` — text-preserving redaction via PDFium (the same engine the Mac app uses; the words are removed from the file, not just covered)\n- `fill_form` — fill AcroForm fields, save with values preserved\n- `flatten` — bake filled forms / annotations into the page stream\n- `sign` — visible signature placement, signed-PDF write\n- `compress` — recompress images / streams to shrink file size\n- `annotate` — programmatic highlight / underline / sticky-note\n- `autocrop` — detect content bounds and crop margins\n- `batch` — apply any tool across a glob of files\n- `ocr` — Apple Vision OCR (Mac only, on-device, CJK-strong)\n\nA buy-once Pro key will be available via [Lemon Squeezy](https://lemonsqueezy.com/) at launch (target: USD 29, includes 12 months of updates). Owners of the [TruePath PDF Mac app](https://joytruepath.com/truepath-pdf?utm_source=github&utm_medium=referral&utm_campaign=2026-07-pdf-readme) will be able to redeem their App Store receipt for a Pro MCP key via an in-app button.\n\n## License\n\nMIT for the MCP shell. Transitive dependencies:\n- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) — MIT\n- [`pdfjs-dist`](https://github.com/mozilla/pdf.js) — Apache 2.0\n- [`pdf-lib`](https://github.com/Hopding/pdf-lib) — MIT\n- [`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas) — MIT\n- [`zod`](https://github.com/colinhacks/zod) — MIT\n\nPro tier will additionally bundle a prebuilt [PDFium](https://pdfium.googlesource.com/pdfium/) library (BSD/Apache, the same one used by Chrome).\n\n## Contact\n\n- Issues: <https://github.com/JoyTruepath/truepath-pdf-mcp/issues>\n- Mail: support@joytruepath.com\n- Joy Truepath Pte. Ltd., Singapore (UEN 202205336E)\n",
  "bytes": 6610,
  "sha": "24fc93fd50187ddf5b20203334784ec4e6b9c5800fbf96d99210a6971e6acfcc",
  "repo_slug": "joytruepath/truepath-pdf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_joytruepath_truepath_pdf_mcp_0d7ad8b9/readme"
}