PDF Reader (PDF Agent Stack)

PDF Reader MCP Server

English | 日本語

An MCP (Model Context Protocol) server specialized in deciphering PDF internal structures.

While typical PDF MCP servers are thin wrappers for text extraction, this project focuses on reading and analyzing the internal structure of PDF documents. Pair it with pdf-spec-mcp for specification-aware structural analysis and validation.

PDF family

pdf-reader-mcp inspects signature structure (inspect_signatures); for cryptographic signature verification, trust/revocation evaluation, and PDF/A conformance validation, use pdf-verify-mcp.

Features

18 tools organized into three tiers:

Tier 1: Basic Operations

Tier 2: Structure Inspection

Tier 3: Comparison

validate_tagged and validate_metadata were removed (deprecated since 0.7.0). This server reports what a PDF contains and does not return pass/fail against a standard. For PDF/UA or PDF/A conformance, use pdf-verify-mcp validate_conformance (flavour: "pdfua-1", "pdfa-*", …). For the facts those tools used to look at, use inspect_tags (structure tree) and get_metadata (metadata fields) here.

read_url and the read-only boundary (#25)

read_url returns text, and only text. This is a decision, now stated rather than implied: the fetched bytes are discarded after extraction, because saving them would make a reader tool write to the file system, and every tool of this server is read-only (readOnlyHint: true — all 18 of them).

To run search_text, inspect_structure, extract_tables, render_page or anything else against a PDF that lives at a URL, download the file first — with whatever fetch capability the calling environment has — and pass the local path. Fetching is the caller's responsibility, deliberately: an agent environment always has a way to download a file, and a reader that also writes files has stopped being a pure observer.

read_url remains the right tool for the one-shot question: *what does the document at this URL say?*

Pages can be rendered when text cannot be read (#23)

summarize reporting hasText: false used to be a dead end: nothing in this server could read the document any further. render_page closes that — it rasterises pages to PNG or JPEG and returns them as MCP image content blocks, so a vision model can read a scan, a diagram, a filled form, or handwriting.

render_page({ file_path: "/path/to/scan.pdf", pages: "1-3", format: "jpeg" })

pages is required: rendering is the most expensive operation here, and "all pages" of a 500-page scan should be a decision, not a default. The same 4 MB response budget as read_images applies, with omissions named.

Rendering runs on PDFium compiled to WebAssembly (@hyzyla/pdfium, an optional dependency). A WASM binary is the same bytes on every platform, so the published package still behaves identically wherever npx runs it — the reason native addons are not used here. Without the dependency installed, render_page reports what to install and every other tool works normally. PDFium (BSD-3-Clause) is a different engine from the pdf.js this server reads text with; the tool description says so, because a rendering difference between engines must not be attributed to the file.

Measured before choosing this: pdf.js + @napi-rs/canvas (1.0.7 and 0.1.80) segfaults the

whole process on pages that draw images — exactly the pages this tool exists for — and

renders blank pages when standardFontDataUrl is not configured.

Images come back as image files (#22)

read_images used to base64 imgData.data — pdfjs's *decoded pixels*. An 8×8 RGB image was 192 bytes with no PNG or JPEG signature anywhere in it, so the result could not be opened by any viewer and could not be read by a vision model, which is the reason to extract an image in the first place.

Images are now encoded (PNG by default, lossless; format: "jpeg" with quality when smaller matters) and returned as MCP image content blocks, with the metadata alongside in a text block. Both encoders are written out here — no native addon, no per-platform binary.

The response is bounded at 4 MB of encoded image data. A 200 dpi A4 scan is ~11.6 MB of pixels on its own, so images past the budget are named with the reason rather than dropped:

read_images({ file_path: "/path/to/scan.pdf", pages: "1", max_width: 1200, format: "jpeg" })

read_images returns the image XObjects a page draws. It is not a picture of the page — vector drawings and text are not covered by it.

Text extractability — three states, not two (#21)

read_text used to answer with text or with nothing, and nothing meant three different things. ISO 32000-2 §9.10.1 separates them, so this server does too. Every text-returning tool — read_text, read_url, search_text, extract_structured_text, summarize — reports, per page:

not_extractable is reported per font, so a page that mixes a readable font with an unreadable one is a partial loss and says so, rather than passing as complete.

The observation is made from the file, not from pdf.js's output: pdf.js synthesises a toUnicode map for every font it loads, so asking it whether a font has a /ToUnicode CMap answers yes for fonts whose dictionary has none.

Installation

npx (recommended)

npx @shuji-bonji/pdf-reader-mcp@latest

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "pdf-reader-mcp": { "command": "npx", "args": ["-y", "@shuji-bonji/pdf-reader-mcp@latest"] } } }

Use `@latest`. The -y flag in npx -y only skips the install

prompt — it does not check for updates. Without @latest, npx keeps

running whichever version it cached the first time, so new releases never

reach you. If you suspect you are on a stale version, run

rm -rf ~/.npm/_npx and restart your client.

Claude Code

claude mcp add pdf-reader-mcp -- npx -y @shuji-bonji/pdf-reader-mcp@latest

From Source

git clone https://github.com/shuji-bonji/pdf-re