📄 @sylphx/pdf-reader-mcp

The PDF intelligence layer for AI agents that need source evidence, not just extracted text.

V3 smart tool surface · Agent Document Twin · Evidence-first extraction · Visual crops · OCR adapters · Tables, charts, formulas, figures · Trust & accessibility reports · Benchmark-gated releases

PDFs are not plain text files. They are layout, pixels, tables, hidden text, permissions, annotations, scanned pages, and ambiguous reading order.

PDF Reader MCP turns that mess into an Agent Document Twin: a linked, source-backed representation of the PDF that agents can inspect, search, verify, crop, OCR, enrich, cite, and read with confidence.

If your agent has ever hallucinated from a PDF, lost a table, trusted hidden text, missed a scanned page, or needed to cite the exact region that proves an answer, this is the MCP server for that workflow.

Why Agents Use It

Quick Start

Claude Code

claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

Any MCP Client

npx @sylphx/pdf-reader-mcp

Node.js >=22.13 is required. The default package works without downloading OCR models, vision models, Ollama, LM Studio, llama.cpp, or cloud credentials.

Need Cursor, VS Code, Windsurf, Cline, Warp, HTTP transport, Docker, or filesystem sandboxing? See the installation guide.

One Smart Tool First

The default V3 agent path is one tool call:

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

With no manual include_* flags, read_pdf profiles each PDF, chooses the extraction route, and returns the Agent Document Twin in one response. Digital text PDFs get Markdown, chunks, tables, layout routing, and source evidence. Mixed or scanned PDFs are routed toward configured OCR and visual providers when those providers are ready. Metadata, page geometry, warnings, provider readiness, and the selected read_pdf arguments are included so the agent can see what happened.

Agents can still force auto: false and use explicit include_* options for a precise manual extraction. Use auto_detail: "fast", "balanced", or "full" when the agent wants to control output depth without learning dozens of switches.

MCP Tool Surface

Full request and response details live in the API reference.

Agent Document Twin

The Agent Document Twin is the main reason to use this project instead of a plain text extractor. It keeps the document readable by agents while preserving the evidence needed to verify the answer.

Example: Read With Evidence

{
  "sources": [{ "path": "/absolute/path/to/report.pdf" }],
  "include_markdown": true,
  "include_chunks": true,
  "include_tables": true,
  "include_text_layer": true,
  "include_document_map": true,
  "include_document_ast": true,
  "include_trust_report": true,
  "include_accessibility_report": true
}

Example: Search, Then Verify The Source Region

{
  "sources": [{ "path": "/absolute/path/to/report.pdf" }],
  "query": "revenue recognition",
  "max_matches_per_source": 10
}

Use the returned page and bounding box with pdf_evidence operation render_page or extract_regions when the agent needs visual proof before citing or summarizing.

Provider-Enabled Intelligence

The default package stays TypeScript-first and local-first. Heavy engines are optional, deployment-controlled adapters.

Supported visual provider paths include local commands, local HTTP servers, Ollama, OpenAI-compatible endpoints, LM Studio, and llama.cpp. Request payloads cannot choose arbitrary executables or arbitrary provider URLs; providers are configured by the deployment environment.

# Example shape only. Point these at your own local OCR command.
export MCP_PDF_OCR_COMMAND="tesseract"
export MCP_PDF_OCR_ARGS_JSON='["{input}", "stdout", "tsv"]'

See the guide and API reference for provider configuration details.

Release Proof

Strong README claims should be backed by shipped evidence. This repo publishes machine-readable artifacts and gates releases on them.

Run the same proof locally:

bun run benchmark:release-artifacts
bun run benchmark:release-gate
bun run package:smoke

See performance and release evidence for the full benchmark contract.

Output Formats

read_pdf can return the same PDF in several agent-friendly forms:

• Plain text and page text
• Markdown for RAG and summarization
• HTML for rendering or downstream transformation
• Structured elements with page and geometry provenance
• Document AST for semantic navigation
• Citation chunks with page, element, table, and bbox references
• Tables with rows, cells, geometry, warnings, and confidence
• Trust and accessibility reports
• Agent Document Twin indexes linking text, visual, OCR, table, trust, and accessibility evidence

Security Model

PDFs can contain hostile or misleading content. The server treats extraction as an evidence workflow, not as a trusted text dump.

• Local-first by default.
• URL loading is guarded by host, private-IP, size, and HTTP policy controls.
• OCR and visual providers are configured by environment, not by request body.
• Trust reports surface hidden text, near-invisible geometry, off-page text, overlapping text, unsafe links, redaction signals, and prompt-injection-like content.
• Rendering, crops, OCR, and visual enrichment preserve provenance so agents can route weak evidence to verification instead of silently trusting it.

Documentation

Development

git clone https://github.com/SylphxAI/pdf-reader-mcp.git
cd pdf-reader-mcp
bun install
bun run build
bun test

Useful checks:

bun run check
bun run typecheck
bun run docs:build
bun run package:smoke
bun run benchmark:release-gate

Support

• Issues
• Discussions
• npm package

If you want local-first, evidence-backed PDF intelligence to keep improving for AI agents, star the repo. It helps the project reach more builders who need PDFs to be verifiable, not just readable.

License

MIT © SylphxAI

Star History