pdf-reader-mcp

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.

See skills/citra/SKILL.md.

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).

Missing native package → fail closed (no silent engine switch).

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

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/citra package 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.

Three tools. One product surface.

Minimal call:

{
  "sources": [{ "path": "/absolute/path/to/report.pdf" }]
}

1. Financial reports — extract table cells agents can cite by page and geometry
2. Research papers — headings, reading order, page-level quotes
3. Scanned documents — OCR path with evidence, not a text soup

Compare full clean installs, not “JS wrapper tarball vs native executable”:

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

Controlled same-host linux-x64 dual-mode A/B vs @sylphx/pdf-reader-mcp@3.0.14, using registry-installed 4.1.x natives:

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

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.

• Before/after + flagship workflows
• Example demos

• Website / guide
• Installation
• Comparison
• Migration / recovery (secondary)

MIT

If this saves your agents from PDF hallucinations, star the repo and share a demo with your team.