Summary
The Pdf Reader Mcp server provides AI agents with enterprise-grade PDF processing capabilities, enabling extraction of text, images, and metadata from PDF documents. It offers tools for parallel PDF processing with Y-coordinate based content ordering, flexible path handling, and per-page error resilience, achieving 5-10x faster performance compared to sequential processing. The server solves the problem of slow, unreliable PDF extraction by combining high-performance parallel processing with comprehensive error handling and natural content ordering that preserves document layout.
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 →
