📄 PDF Reader MCP

Your agent read the PDF. Did it read the truth?

The most-starred PDF MCP server on GitHub. One call turns any PDF into an Agent Document Twin — structured text, tables, trust signals, and source evidence you can search, crop, and cite.

Local-first · One smart read_pdf call · Evidence with page + bbox · 397 tests · 39/39 release-gate checks

⭐ Star this repo if agents should cite PDFs with proof, not guess from plain text. · Quick start · See it work · Roadmap · Why not plain text?

---

The problem

PDFs are not text files. They are layout, pixels, tables, hidden text, scanned pages, and reading order that breaks the moment you flatten them.

Most PDF tools give agents a text dump. Tables disappear. Scanned pages go blank. Hidden text sneaks in. Citations become guesses. Then the model hallucinates — confidently.

PDF Reader MCP is built for the moment your agent needs to prove an answer, not just sound plausible.

Why not a plain text dump?

Full capability matrix: comparison guide.

See it work

Install once. Call once.

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

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

read_pdf inspects the PDF, picks the extraction route, and returns the Agent Document Twin — no manual include_* flags required:

{
  "auto_read": {
    "workflow": "digital_text_route",
    "selected_arguments": {
      "include_markdown": true,
      "include_tables": true,
      "include_chunks": true,
      "include_trust_report": true,
      "include_document_map": true
    }
  },
  "markdown": "# Annual Report 2026\n\n## Executive Summary\n\n...",
  "tables": [
    {
      "page": 5,
      "cells": [
        { "row": 0, "col": 0, "text": "Quarter", "bbox": [72, 650, 180, 670] },
        { "row": 0, "col": 1, "text": "Revenue", "bbox": [200, 650, 300, 670] }
      ],
      "confidence": 0.95
    }
  ],
  "trust_report": { "risk_level": "low", "findings": [] }
}

Abbreviated shape — see full example and workflows.

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 (render_page or extract_regions) when the agent needs visual proof before citing.

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.

Docker

# Pre-built image from GitHub Container Registry
docker run --rm -i -v /path/to/pdfs:/workspace ghcr.io/sylphxai/pdf-reader-mcp

# Or build locally
docker build -t pdf-reader-mcp . && \
  docker run --rm -i -v /path/to/pdfs:/workspace pdf-reader-mcp

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

MCP Tool Surface

Full request and response details live in the API reference.

Agents can force auto: false for precise manual extraction, or use auto_detail: "fast", "balanced", or "full" to control output depth without learning dozens of switches.

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
}

Provider-Enabled Intelligence

The current package stays local-first. The roadmap target is a Rust MCP server with the same public tool contract, plus optional deployment-controlled providers for OCR and visual enrichment.

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

Claims are backed by shipped, machine-readable artifacts. Releases do not ship unless the gate passes.

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

Help this reach more builders

If PDF hallucinations have wasted your context, your citations, or your trust in agent output, you are exactly who this project is for.

⭐ Star the repo — it is the fastest way to help more agent builders find evidence-first PDF reading. Share it in your MCP client setup, team wiki, or agent stack README.

Discovery (in progress)

Know another MCP directory? Open an issue with the link.

License

MIT © SylphxAI

Star History