Summary
The Pdf Reader Mcp server provides production-ready PDF processing capabilities for AI agents, enabling extraction of text, images, and metadata from PDF files. It delivers 5-10x faster parallel page processing compared to sequential approaches, implements Y-coordinate-based content ordering to preserve document layout, and offers flexible path handling for both absolute and relative file references across Windows and Unix systems. The server solves the performance and reliability challenges of traditional PDF processing through automatic parallelization, per-page error resilience, and comprehensive type safety with 94%+ test coverage.
Give your AI agent a complete email layer—sending, inbound inboxes, and sandbox testing.
Get 4K emails/month free →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Capacitor makes coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Citra
Give your AI agent eyes for PDFs.
Citra is a local-first PDF evidence product for agents — fast, citeable, owned entirely in this repository.
Turn PDFs into structured text, tables, OCR, visual evidence, and page-level citations — locally — via SDK, CLI, or MCP.
Plain-text PDF tools make agents guess. Citra returns proof.
Package (transition): @sylphx/pdf-reader-mcp · bin pdf-reader-mcp
Product docs
| Doc | Purpose |
|---|---|
| docs/POSITIONING.md | Strategic positioning |
| docs/COMPETITIVE.md | Peer anchors and wedge |
| docs/EVIDENCE_CONTRACT.md | Evidence = result contract |
| docs/TOOL_SURFACE.md | Few clear tools policy |
| docs/PRODUCT_INDEPENDENCE.md | This repo is SSOT |
| docs/IPPB.md | Independent public product bar |
| docs/PUBLISH.md | npm/git publish status |
Why this exists
Most PDF tools dump text. Agents then invent page numbers, miss tables, and cite the wrong cell.
Citra returns an Agent Document Twin: markdown + structure + geometry + provenance your agent can actually trust.
| Without evidence | With Citra |
|---|---|
| “The revenue was about $12M” | “Page 14, Table 3, cell (row 4, col 2) = $12.4M” |
| Lost table structure | Rows, columns, cells, bounding boxes |
| Scanned PDF becomes noise | OCR path with page-linked evidence |
| Hidden text / prompt injection ignored | Trust signals when requested |
Agent skill surface
Install (30 seconds)
npm install -g @sylphx/pdf-reader-mcp
Or pin the current release:
npm install -g @sylphx/pdf-reader-mcp@4.1.1
One native binary is installed for your platform only (not all five).
| Platform | Native package (auto optionalDependency) |
|---|---|
| macOS arm64 | @sylphx/pdf-reader-mcp-darwin-arm64 |
| macOS x64 | @sylphx/pdf-reader-mcp-darwin-x64 |
| Linux x64 | @sylphx/pdf-reader-mcp-linux-x64-gnu |
| Linux arm64 | @sylphx/pdf-reader-mcp-linux-arm64-gnu |
| Windows x64 | @sylphx/pdf-reader-mcp-win32-x64-msvc |
Missing native package → fail closed (no silent engine switch).
Quick start
Claude Code
claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp
Claude Desktop / Codex / Cursor / VS Code / any MCP client
{
"mcpServers": {
"pdf-reader": {
"command": "npx",
"args": ["@sylphx/pdf-reader-mcp"]
}
}
}
Dual-era hosts that send server/discover before initialize (e.g. Gemini Antigravity CLI) are supported on stdio — the server answers discovery and keeps the session open for the legacy handshake.
Stdio / HTTP
pdf-reader-mcp
MCP_TRANSPORT=http pdf-reader-mcp
SDK (programmatic)
Citra is not MCP-only. Apps and internal dogfood can call the same engine without a chat client.
TypeScript — spawn the native server as a client
import { Citra } from '@sylphx/pdf-reader-mcp/sdk';
const citra = Citra.create();
const { payload, isError } = await citra.read({
sources: [{ path: '/absolute/path/to/doc.pdf' }],
// auto defaults on when you omit include_* flags
});
if (isError) throw new Error(JSON.stringify(payload));
console.log(payload);
Low-level escape hatch: @sylphx/pdf-reader-mcp/pure-rust (createPureRustClient).
- Export:
@sylphx/pdf-reader-mcp/sdk→Citra(read/search/evidence) - Export:
@sylphx/pdf-reader-mcp/pure-rust→createPureRustClient,resolvePureRustServerBinary,PureRustClient - Tools (same as MCP):
read_pdf·search_pdf·pdf_evidence - Requires the platform optional native package (same as MCP install)
- Roadmap: idiomatic high-level
@sylphx/citrapackage name + richer typed SDK; semantics stay isomorphic with CLI/MCP
CLI
npx pdf-reader-mcp --help # transitional bin
# doctor / read paths: see package bin and docs/guide
MCP — see Quick start above (npx @sylphx/pdf-reader-mcp).
Independence: this product only. No central Instruments monorepo.
What you get
Three tools. One product surface.
| Tool | What agents use it for |
|---|---|
read_pdf | Smart default: markdown, tables, structure, OCR, citations |
search_pdf | Find page + snippet matches before deep reading |
pdf_evidence | Crops, renders, inspect, focused evidence ops |
Minimal call:
{
"sources": [{ "path": "/absolute/path/to/report.pdf" }]
}
Flagship use cases
- Financial reports — extract table cells agents can cite by page and geometry
- Research papers — headings, reading order, page-level quotes
- Scanned documents — OCR path with evidence, not a text soup
Install footprint (honest product comparison)
Compare full clean installs, not “JS wrapper tarball vs native executable”:
| Metric (measured clean install, linux-x64) | Historical TS 3.0.14 | Sole-Rust 4.1.0 |
|---|---|---|
| Main package on disk | ~403 KB | ~77 KB |
Full node_modules | ~82.3 MiB | ~24.4 MiB (~3.4× smaller) |
| Installed files | 4,101 | 20 (~205× fewer) |
| Production npm dependency graph | PDF.js + MCP TS SDK + more | {} + one platform native |
The native binary is multi-megabyte because it is the PDF intelligence engine (parser, server, rendering/table/OCR routing). That is expected and still yields a cleaner, smaller install than shipping PDF.js + a JS dependency tree.
Details: installed footprint comparison
Performance
Controlled same-host linux-x64 dual-mode A/B vs @sylphx/pdf-reader-mcp@3.0.14, using registry-installed 4.1.x natives:
| Mode | What it measures | Result |
|---|---|---|
persistent_warm | long-lived server, repeated identical local read_pdf after warm-up | ≥ ~10× median latency improvement on all 8 required fixture classes |
startup_inclusive | spawn + initialize + one task | large advantage on the same fixtures |
persistent_warm includes a process-local cache for identical local path+options. First request in a process still pays full parse cost.
Also: install footprint is much smaller than TS 3.0.14 on measured linux-x64 (~3.4× less disk, ~205× fewer files), and the 4.1.0 native binary is smaller than 4.0.2 (strip/LTO).
Not a multi-host guarantee. Details: 4.1.0 report · claims policy
Engine note
Version 4 runs a native Rust engine on supported platforms via a thin Node launcher.
Local-first. Five platforms. One clean install.
Unusually formed or broken ToUnicode CMaps are handled without crashing, and the release binary is built panic-unwind so a worker-thread panic fails the affected request instead of aborting the whole process (#608).
Engineering history, recovery pins, and ADRs live under docs/migration.md — not the product pitch.
Product proof
Docs
License
MIT
If this saves your agents from PDF hallucinations, star the repo and share a demo with your team.
Featured
Give your AI agent a complete email layer—sending, inbound inboxes, and sandbox testing.
Get 4K emails/month free →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Capacitor makes coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
