@shuji-bonji/pdf-reader-mcp
Read-only PDF inspection and analysis server for extracting content, examining internal structure, validating metadata/tagging, and comparing documents.
Get page counts, metadata, summaries, and extract or search text with page ranges, column-aware ordering, and whitespace compaction.
Fetch and extract text from remote PDF URLs.
Extract embedded images as base64-encoded data.
Inspect catalog/page-tree/object structure, tagged-PDF structure, fonts, annotations, and digital signature field structure.
Extract tables from tagged PDFs.
Validate tagged PDF structure for PDF/UA-style checks and validate metadata best practices.
Compare two PDFs structurally, including properties, fonts, object counts, catalog entries, and signatures.
Note: signature inspection is structural only, not cryptographic verification.
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
Server | Role |
PDF specification knowledge (ISO 32000, PDF/A, PDF/UA) | |
pdf-reader-mcp (this) | Read and inspect PDF internal structure — what is in a PDF |
Authenticity verification — whether it is genuine: cryptographic signature verification, tamper detection, PAdES level, PDF/A validation, encrypted-PDF decryption |
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
Tool | Description |
| Lightweight page count retrieval |
| Full metadata extraction (title, author, PDF version...) |
| Text extraction with Y-coordinate reading order (opt-in |
| Full-text search with surrounding context. Searches the same text |
| Embedded image XObjects as PNG or JPEG files, returned as MCP image content blocks so a vision model can read them. |
| Fetch a remote PDF and extract its text — nothing more. The bytes are not saved; to use the other 17 tools on a URL's PDF, download it first and pass the local path (see "read_url and the read-only boundary") |
| Rasterise pages to PNG/JPEG via PDFium-WASM (optional dependency |
| Quick overview report (metadata + text + image count + per-document text extractability) |
Tier 2: Structure Inspection
Tool | Description |
| Object tree and catalog dictionary analysis |
| Document-level inventory from the catalog (ISO 32000-2 §7.7.2): bookmarks ( |
| Tagged PDF structure tree visualization |
| Font inventory (embedded/subset/type detection) |
| Annotation listing (categorized by subtype) |
| Digital signature field structure analysis |
| Tagged PDF text in logical content order (ISO 32000-2 §14.8.2.5), each piece labelled with its structure type ( |
| Tagged PDF |
| Object number → page and rectangle, in the coordinate form pdf-writer-mcp |
Tier 3: Comparison
Tool | Description |
| Structural diff between two PDFs (properties + fonts) |
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 whenstandardFontDataUrlis 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:
State | Condition | What to do next |
| Every font used has a route to Unicode under §9.10.2 | Use the text |
| No text-showing operator ( | The page is pixels. OCR or a rendered image is needed; this server does neither |
| A font used has no | Text is missing or wrong. The report names the fonts and the clause |
| Encrypted, or the content stream could not be read | Nothing was measured. Not the same as "nothing is there" |
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.
Related MCP server: PDF Reader MCP Server
Installation
npx (recommended)
npx @shuji-bonji/pdf-reader-mcp@latestClaude 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-yflag innpx -y <pkg>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, runrm -rf ~/.npm/_npxand restart your client.
Claude Code
claude mcp add pdf-reader-mcp -- npx -y @shuji-bonji/pdf-reader-mcp@latestFrom Source
git clone https://github.com/shuji-bonji/pdf-reader-mcp.git
cd pdf-reader-mcp
npm install
npm run buildUsage Examples
Get Page Count
get_page_count({ file_path: "/path/to/document.pdf" })
→ 42
get_page_count({ file_path: "/path/to/document.pdf", response_format: "json" })
→ { "pageCount": 42,
"scope": { "declaredCount": 42, "pagesReached": 42, "pageTree": { "status": "read" } } }declaredCount is the /Count the page tree declares (ISO 32000-2 §7.7.3.2) and pagesReached
is how many pages walking the tree actually reached. They differ only when the writer got
/Count wrong; both are reported and neither is judged.
Metadata from both sources
get_metadata reads the eight document-level fields (title, author, subject, keywords, creator,
producer, creation and modification dates) from the document information dictionary (§14.3.3)
and the XMP metadata stream (§14.3.2). When both hold a value, PDF 2.0 and later use XMP
(§14.3.3 deprecates the dictionary for this in PDF 2.0) and earlier versions use the dictionary.
The two dates are the exception: they use the dictionary in every version, because §14.3.3 does
not deprecate CreationDate and ModDate, and §14.5 compares PieceInfo's LastModified with
the dictionary's ModDate.
metadataSources names the source of each field, and metadataConflicts lists the fields whose
two values differ (dates compared as instants). Values are returned as written — a dictionary
date looks like D:20260915100000+09'00', an XMP date like 2026-09-15T10:00:00+09:00.
Search Text
search_text({
file_path: "/path/to/spec.pdf",
query: "digital signature",
pages: "1-20",
max_results: 10
})
→ Found 5 matches (page 3, 7, 12, 15, 18)Summarize
summarize({ file_path: "/path/to/document.pdf" })
→ | Pages | 42 |
| PDF Version | 2.0 |
| Tagged | Yes |
| Signatures | No |
| Images | 15 |Compare Structure
compare_structure({
file_path_1: "/path/to/v1.pdf",
file_path_2: "/path/to/v2.pdf"
})
→ | Page Count | 10 | 12 | ❌ |
| PDF Version | 1.7 | 2.0 | ❌ |
| Tagged | true | true | ✅ |Extract Structured Text (Tagged PDF, logical order)
extract_structured_text({ file_path: "/path/to/report.pdf", pages: "1-2" })
→ # Structured Text
- **Tagged**: Yes / **Language**: en-US / **Elements**: 7
## Logical Content Order
- **Document** (pages 1–2)
- **H1** (page 1) — Quarterly Report
- **P** (pages 1–2) — This paragraph begins on page one and continues on page two.
- **Table** (page 1)
| Item | Amount |
|---|---|
| Sales | 100 |
- **Figure** (page 2) — *alt:* A bar chart of salesThis answers "what is the text of the H1?" — which read_text (flat,
coordinate order) cannot. Order is a depth-first traversal of the structure
tree (ISO 32000-2 §14.8.2.5). /ActualText replaces the glyphs (§14.9.4),
/Alt stays out of the body text (§14.9.3), list labels are reported
separately, a list nested in an item comes back as its own L / LI
elements after the item (not folded into the item's text, pages or boxes —
the nested L's own boxes cover the nested items), and an element
spanning a page break stays ONE element. Use
roles: ["H1", "H2"] to pull an outline. Untagged PDFs return
isTagged: false with a reason — nothing is guessed from coordinates.
include_bbox: where the element is drawn
extract_structured_text({ file_path: "/doc.pdf", roles: ["P"], include_bbox: true })
→ - **P** (page 1) — Measured paragraph
- *bbox* p1 `(50.0, 297.5, 161.4, 308.6)` — text-extent
- **Figure** (page 1)
- *bbox* p1 `(50.0, 150.0, 110.0, 190.0)` — layout-attribute-bboxRectangles are in PDF default user space (origin bottom-left, pt, normalised) —
exactly what pdf-writer-mcp
add_annotation takes, so "annotate this paragraph" needs no coordinate
conversion in between. /Rotate and a shifted /CropBox do not move them.
basis says how strong the claim is, and the two are different in kind:
| What it is |
| The |
| Measured from the element's text: baseline origin plus the font's ascent/descent. The line box, not the glyph outlines. Images and vector art contribute nothing |
An element spanning pages gets ONE RECTANGLE PER PAGE — merging them would put
content on a page it is not on. An element with no rectangle says why in
boxNote rather than returning a zero-sized one.
A declaration is reported as-is, and cross-checked. Files state nonsense:
the cover Figure of both Well-Tagged PDF 1.0 and the Tagged PDF Best Practice
Guide declares /BBox [-32768 -32768 32767 32767] — int16 sentinels where a
rectangle should be — and PDF32000_2008 has 131 of its 545 declarations reaching
past the page edge. Since this output is meant to go straight into
add_annotation, a declaration is checked against the page box (§7.7.3.3) and
against the element's own text; either contradiction is reported in boxNote,
with the rectangle still returned unaltered.
Measured against independent ground truth: on Well-Tagged PDF (WTPDF) 1.0, the
166 Link structure elements were compared with the 173 Link annotation
/Rect values the producer placed for the same links — median IoU 0.972,
none disjoint.
Extract Tables (Tagged PDF)
extract_tables({ file_path: "/path/to/kaisei-tsutatsu.pdf", pages: "1" })
→ # Extracted Tables
- **Tagged**: Yes / **Pages Scanned**: 1 / **Tables Found**: 1
## Table 1 — Page 1
| 改正後 | 改正前 |
| --- | --- |
| …第2条第 16 項《定義》… | …第2条第 15 項《定義》… |A table that continues across a page break is reported as ONE table —
pages is an array (e.g. ## Table 3 — Pages 5–7), and a table touching
the requested pages range is returned whole. Cell text honours
/ActualText replacements (as do read_text and search_text since #18).
Untagged PDFs return an empty result with a
note recommending the column-aware fallback below.
Read Untagged Multi-Column PDF
read_text({ file_path: "/path/to/older-shinkyu.pdf", split_columns: 2 })
→ // Plain Y-sort would interleave columns:
// "改正後セル1 改正前セル1\n 改正後セル2 改正前セル2..."
//
// With split_columns: 2 the left column is emitted first, then the right:
// "改正後セル1\n改正後セル2\n…\n\n改正前セル1\n改正前セル2\n…"Use split_columns: 2 | 3 for untagged multi-column PDFs. For Tagged
PDFs with proper <Table> markup, extract_tables (above) is preferred.
Compact Whitespace (Japanese Forms)
read_text({ file_path: "/path/to/form.pdf", compact_whitespace: true })
→ // Original PDF uses U+3000 fullwidth space as visual indentation:
// " ( ) 自 年 月 日 法 有 ( 年 月 日) 有 有"
//
// With compact_whitespace: true:
// "( ) 自 年 月 日 法 有 ( 年 月 日) 有 有"
//
// Empirically reduces character count by ~40% on form PDFs.compact_whitespace is orthogonal to split_columns — both can be combined.
Tech Stack
TypeScript + MCP TypeScript SDK
pdfjs-dist (Mozilla) — text/image extraction, tag tree, annotations
normativepdf + @normativepdf/recover — COS object access, read from files whose cross-reference table does not follow ISO 32000-2 §7.5
Vitest — unit + E2E testing (483 tests)
Biome — linting + formatting
Zod — input validation
Testing
npm test # Run all tests (unit + E2E: 483 tests)
npm run test:e2e # E2E tests only (283 tests)
npm run test:watch # Watch modeArchitecture
pdf-reader-mcp/
├── src/
│ ├── index.ts # MCP Server entry point
│ ├── constants.ts # Shared constants
│ ├── types.ts # Type definitions
│ ├── tools/
│ │ ├── tier1/ # Basic tools (7)
│ │ ├── tier2/ # Structure inspection (6)
│ │ ├── tier3/ # Validation & analysis (3)
│ │ └── index.ts # Tool registration
│ ├── services/
│ │ ├── pdfjs-service.ts # pdfjs-dist wrapper (parallel page processing)
│ │ ├── recover-service.ts # @normativepdf/recover — opening a document,
│ │ │ # and how far it could be read (DocumentScope)
│ │ ├── structure-service.ts # Catalog, page tree, object statistics
│ │ ├── font-service.ts # Fonts named in each page's /Resources
│ │ ├── signature-service.ts # Signature fields of the AcroForm (structure only)
│ │ ├── content-stream-service.ts # Marked-content operators, text-showing tally
│ │ ├── struct-tree-service.ts # Logical structure (tags, structured text)
│ │ ├── validation-service.ts # Validation & comparison logic
│ │ └── url-fetcher.ts # URL fetching
│ ├── schemas/ # Zod validation schemas
│ └── utils/
│ ├── pdf-helpers.ts # PDF utilities (page range parsing, file I/O)
│ ├── batch-processor.ts # Batch processing for large PDFs
│ ├── formatter.ts # Output formatting
│ └── error-handler.ts # Error handling
└── tests/
├── tier1/ # Unit tests
└── e2e/ # E2E tests (16 suites, 283 tests)Error Contract (houki-hub family)
Since v0.6.0, this MCP returns structured errors that follow the houki-hub family error contract, sharing a unified code vocabulary across the family. Combined with houki-egov-mcp / houki-nta-mcp, an LLM or Skill layer can interpret errors with consistent logic.
docs/ERROR-CODES.md— error code vocabulary (houki-research-skill)docs/ERROR-HANDLING.md— handling policy / next_actions templates
Implementation is independent — no dependency on houki-abbreviations or other family packages. The reference implementation is houki-egov-mcp/src/errors.ts; pdf-reader-mcp's local definition is in src/errors.ts.
On error, every tool returns isError: true and the JSON-stringified LawServiceError in content[0].text:
{
"error": "The file does not appear to be a valid PDF.",
"code": "INVALID_PDF",
"retryable": false,
"hint": "The file breaks a structural rule of ISO 32000 (for example, it does not begin with %PDF- (§7.5.2), or it does not end with startxref and %%EOF (§7.5.5)), so it cannot be read as written. This is a finding about the file, not a failure of this server.",
"next_actions": [
{
"action": "inspect_structure",
"reason": "Look at the catalog and the page tree to see where the file stops following the specification."
}
],
"detail": { "cause": "The PDF file is empty, i.e. its size is zero bytes." }
}Every error carries error (an English sentence), code and retryable; hint, next_actions and detail are optional, and nothing else appears at the top level (PDF family contract, pdf-agent-stack docs/specs/06 §2.3, since v0.19.0). retryable is fixed per code: it says whether changing the arguments, flags or environment could make the same reading of the same document succeed. The values of next_actions[].action are stable — a Skill may branch on them.
Codes used by pdf-reader-mcp
code | When |
|
| A path, URL or page range the caller passed is wrong (including a URL on a port the Fetch Standard blocks, such as 9) |
|
| No file at the path (ENOENT) |
|
| The file breaks a structural rule of ISO 32000 — empty, not a PDF, or cut short. A finding about the file, not a failure of this server |
|
| The file encryption key cannot be derived from the empty user password. This server takes no password; pass a decrypted copy |
|
| A PDF feature this server does not handle |
|
| Over the 50 MB limit |
|
|
|
|
|
|
|
|
|
|
|
|
|
| A failure inside this server |
|
Migration note (v0.5.x → v0.6.0)
旧 v0.5.x までは content[0].text に Error: ...\n\nSuggestion: ... という人間可読文字列を入れていました。v0.6.0 では同じ場所に JSON 文字列 が入ります。LLM 側でテキスト解釈に依存していた場合は、JSON.parse(content[0].text) での解釈に切り替えてください。isError: true フラグで構造化エラーかどうかを判定できます。
Pairing with pdf-spec-mcp
pdf-spec-mcp provides PDF specification knowledge (ISO 32000-2, etc.). With both servers enabled, an LLM can perform specification-aware workflows:
summarize— get a PDF overviewinspect_tags— examine the tag structurepdf-spec-mcp
get_requirements— fetch PDF/UA requirementspdf-verify-mcp
validate_conformance— check conformance (flavour: "pdfua-1")compare_structure— diff before/after fixes
License
MIT
Available Tools
16 toolscompare_structureCompare PDF StructuresARead-onlyIdempotent
Compare the internal structures of two PDF documents and identify differences.
Args:
file_path_1 (string): Absolute path to the first PDF file
file_path_2 (string): Absolute path to the second PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Structural comparison including: property-by-property diff (page count, PDF version, encryption, tagged status, object counts, page dimensions, file size, catalog entries, signatures), font comparison (fonts unique to each file and shared fonts), and a summary.
Examples:
Compare two versions of the same document
Verify structural consistency across PDF exports
Identify differences in PDF generation pipelines
Inputs: file_path_1 (required), file_path_2 (required), response_format.
extract_tablesExtract Tables (Tagged PDF)ARead-onlyIdempotent
Extract every <Table> subtree from a Tagged PDF as a structured row/cell list,
optionally rendered as Markdown tables.
How it works: walks the StructTree and pulls cell text for each <TR> →
<TH>/<TD>, then collapses kerning whitespace (e.g. "消 費 税 法" → "消費税法").
This sidesteps reading-order extraction's failure mode on multi-column tables
(typical of 新旧対照表 PDFs).
Args:
file_path (string): Absolute path to a local PDF file
pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Markdown — # Extracted Tables summary block followed by one
## Page N — Table M section per table with a GFM table.
JSON — { isTagged, tables: [{ page, index, headerRows, bodyRows, footerRows }], totalTables, pagesScanned, note? }.
Limitations:
Untagged PDFs return an empty result and a
note.colspan/rowspan are not honoured (cells are listed in source order).
Nested tables are skipped to keep page indices stable.
Examples:
Pull 新旧対照表 from a kaisei tsutatsu PDF for diffing
Convert 帳票 (form template) tables into structured data
Inputs: file_path (required), pages, response_format.
get_metadataGet PDF MetadataARead-onlyIdempotent
Extract metadata from a PDF document including title, author, creation date, page count, PDF version, and structural information.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Metadata including: title, author, subject, keywords, creator, producer, creation/modification dates, page count, PDF version, linearized/encrypted/tagged/signature flags, file size.
Examples:
Get document properties for cataloging
Check if a PDF is tagged (accessibility)
Verify PDF version compatibility
Inputs: file_path (required), response_format.
get_page_countGet PDF Page CountARead-onlyIdempotent
Get the total number of pages in a PDF document.
This is a lightweight operation that only reads the PDF header, not the full content.
Args:
file_path (string): Absolute path to a local PDF file
Returns: Page count as a number.
Examples:
Quick check before deciding which pages to extract
Validate a PDF file is readable
Inputs: file_path (required).
inspect_annotationsInspect PDF AnnotationsARead-onlyIdempotent
Extract and categorize all annotations in a PDF document.
Args:
file_path (string): Absolute path to a local PDF file
pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Total annotation count, breakdown by subtype (Link, Widget, Highlight, Text, etc.) and by page, flags for links/forms/markup presence, and individual annotation details.
Examples:
Check for form fields (Widget annotations)
Find all links in a document
Inventory markup annotations (highlights, comments)
Inputs: file_path (required), pages, response_format.
inspect_fontsInspect PDF FontsARead-onlyIdempotent
List all fonts used in a PDF document with their properties.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Font name, type (TrueType, Type1, CIDFont, etc.), encoding, embedded/subset status, and pages where each font is used.
Examples:
Check if all fonts are embedded (required for PDF/A, PDF/X)
Identify font types and encodings
Find which pages use specific fonts
Inputs: file_path (required), response_format.
inspect_signaturesInspect PDF Digital SignaturesARead-onlyIdempotent
Examine digital signature fields in a PDF document.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Total signature field count, signed/unsigned breakdown, and details for each field (signer name, reason, location, signing time, filter/subFilter).
Note: This tool inspects signature field structure only. Cryptographic signature verification is not performed.
Examples:
Check if a PDF has been digitally signed
Inspect signer information and signing dates
Verify signature field structure
Inputs: file_path (required), response_format.
inspect_structureInspect PDF StructureARead-onlyIdempotent
Examine PDF internal object structure including catalog entries, page tree, and object statistics.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Catalog entries (keys and types), page tree info (page count, MediaBox samples), object statistics (total count, stream count, type distribution), and encryption status.
Examples:
Examine document catalog for structural features
Count PDF objects and streams
Check page dimensions across the document
Inputs: file_path (required), response_format.
inspect_tagsInspect Tagged PDF StructureARead-onlyIdempotent
Analyze the Tagged PDF structure tree for accessibility assessment.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Whether the PDF is tagged, the structure tree hierarchy with roles, max nesting depth, total element count, and role distribution (e.g., Document, P, H1, Table, Figure).
Examples:
Check if a PDF is tagged for accessibility (PDF/UA)
Inspect the tag hierarchy and role distribution
Assess document structure quality
Inputs: file_path (required), response_format.
read_imagesRead PDF ImagesARead-onlyIdempotent
Extract images from a PDF document as base64-encoded data.
Extracts embedded images from specified or all pages. Returns image metadata (dimensions, color space) along with raw pixel data in base64.
Args:
file_path (string): Absolute path to a local PDF file
pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
Returns: Array of extracted images with: page number, index, width, height, color space (RGB/RGBA/Grayscale), bits per component, and base64-encoded data.
Note: Large images may produce very large responses. Use the pages parameter to limit scope.
Examples:
Extract all images: { file_path: "/path/to/doc.pdf" }
Extract from page 1: { file_path: "/path/to/doc.pdf", pages: "1" }
Inputs: file_path (required), pages.
read_textRead PDF TextARead-onlyIdempotent
Extract text content from a PDF document with Y-coordinate-based reading order preservation.
Text is extracted page by page, sorted by vertical position (top to bottom) then horizontal position (left to right), providing natural reading order.
For untagged multi-column PDFs (e.g. older 新旧対照表 PDFs that lack a structure tree), pass split_columns: 2 or 3 to bucket items by X-coordinate left-to-right. Tagged PDFs with proper <Table> markup should use the extract_tables tool instead.
For Japanese form-style PDFs (帳票・様式) where U+3000 fullwidth spaces are used as visual indentation, pass compact_whitespace: true to collapse runs of whitespace to a single ASCII space. Cuts 20–40% of token consumption without losing content.
Args:
file_path (string): Absolute path to a local PDF file
pages (string, optional): Page range to extract. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
response_format ('markdown' | 'json'): Output format (default: 'markdown')
split_columns (1 | 2 | 3, optional): Column-aware reordering for untagged multi-column PDFs. Default 1 = existing Y-sort.
compact_whitespace (boolean, optional): Collapse whitespace runs (incl. U+3000) to one ASCII space and trim each line. Default false.
Returns:
Extracted text organized by page number. With split_columns >= 2, columns are separated by a blank line so a downstream LLM can tell them apart.
Examples:
Extract all text: { file_path: "/path/to/doc.pdf" }
Untagged 新旧対照表: { file_path: "/path/to/older-shinkyu.pdf", split_columns: 2 }
Japanese form template: { file_path: "/path/to/form.pdf", compact_whitespace: true }
Inputs: file_path (required), pages, response_format, split_columns, +1 more.
read_urlRead PDF from URLARead-only
Fetch a PDF from a URL and extract its text content.
Downloads the PDF from the specified URL, then extracts text with Y-coordinate-based reading order. Supports HTTP and HTTPS. Maximum file size: 50MB. Timeout: 30 seconds.
Like read_text, accepts split_columns: 2 | 3 for untagged multi-column PDFs and compact_whitespace: true to collapse U+3000 / ASCII whitespace runs. Tagged PDFs should use extract_tables instead.
Args:
url (string): URL pointing to a PDF file (HTTP or HTTPS)
pages (string, optional): Page range to extract. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
response_format ('markdown' | 'json'): Output format (default: 'markdown')
split_columns (1 | 2 | 3, optional): Column-aware reordering. Default 1 = existing Y-sort.
compact_whitespace (boolean, optional): Collapse whitespace runs (incl. U+3000) to one ASCII space. Default false.
Returns: Extracted text organized by page number, same format as read_text.
Examples:
Read remote PDF: { url: "https://example.com/document.pdf" }
Untagged 2-column PDF: { url: "https://...", split_columns: 2 }
Japanese form: { url: "https://...", compact_whitespace: true }
Inputs: url (required), pages, response_format, split_columns, +1 more.
search_textSearch PDF TextARead-onlyIdempotent
Search for text within a PDF document. Returns matching locations with surrounding context.
Case-insensitive search across all or specified pages. Each match includes the page number, the matched text, and configurable surrounding context.
Args:
file_path (string): Absolute path to a local PDF file
query (string): Text to search for (case-insensitive, 1-500 chars)
pages (string, optional): Page range to search. Omit for all pages.
context_chars (number): Characters of context before/after match (default: 80)
max_results (number): Maximum matches to return (default: 20, max: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Search matches with page number, matched text, and surrounding context.
Examples:
Search entire PDF: { file_path: "/path/to/doc.pdf", query: "digital signature" }
Search specific pages: { file_path: "/path/to/doc.pdf", query: "error", pages: "1-10" }
Inputs: file_path (required), query (required), pages, context_chars, +2 more.
summarizeSummarize PDFARead-onlyIdempotent
Generate a quick overview report of a PDF document.
Combines metadata, text presence check, image count, and a text preview from the first page into a single summary. Useful as a first step before deciding which detailed tools to use.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Summary including: page count, PDF version, file size, tagged/encrypted/signature flags, text presence, image count, and a text preview from page 1.
Examples:
Quick overview: { file_path: "/path/to/doc.pdf" }
Machine-readable: { file_path: "/path/to/doc.pdf", response_format: "json" }
Inputs: file_path (required), response_format.
validate_metadataValidate PDF MetadataARead-onlyIdempotent
Validate PDF metadata conformance against best practices and specification requirements.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Validation results including: total checks, pass/fail counts, detailed issues with severity, metadata field presence summary, and an overall summary.
Checks performed:
Title presence (required for PDF/UA, PDF/A)
Author presence
Creation date format validation
Modification date presence
Producer identification
PDF version detection
Tagged flag status
Subject and Keywords presence
Encryption and accessibility impact
Examples:
Verify PDF metadata completeness for PDF/A archival
Check metadata requirements for PDF/UA compliance
Audit document metadata for publishing standards
Inputs: file_path (required), response_format.
validate_taggedValidate Tagged PDFARead-onlyIdempotent
Validate PDF/UA tagged structure requirements.
Args:
file_path (string): Absolute path to a local PDF file
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Validation results including: whether the PDF is tagged, total checks performed, pass/fail counts, detailed issues with severity levels (error/warning/info), and a summary.
Checks performed:
Document marked as tagged
Structure tree root existence
Document root tag presence
Heading hierarchy (H1-H6) sequential order
Figure tags for images
Paragraph tag presence
Structure element count
Table tag structure (TR/TH/TD)
Examples:
Check if a PDF meets PDF/UA accessibility requirements
Identify missing or incorrect tag structure
Assess document accessibility quality
Inputs: file_path (required), response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a specific PDF aspect: text extraction, table extraction, image extraction, metadata, structural inspection, annotation, font, signature, tag accessibility, comparison, search, validation, and summary. No two tools perform the same function; even read_text and read_url differ by source. All purposes are clearly distinct.
All tool names follow a consistent snake_case verb_noun pattern (e.g., extract_tables, inspect_fonts, validate_metadata). The verbs are varied (compare, extract, get, inspect, read, search, validate) but each is appropriate for the action, and there is no mixing of conventions like camelCase.
16 tools is well-scoped for a PDF analysis MCP server. It provides a comprehensive set for reading, inspecting, and validating PDFs without being overwhelming. Each tool earns its place; there are no redundant or trivial tools.
The tool surface covers all major PDF analysis needs: metadata, text (local & URL), tables, images, structure, annotations, fonts, signatures, tags, search, comparison, and validation. There are no obvious gaps; the set allows agents to thoroughly inspect a PDF's content and properties.
Maintenance
Related MCP Connectors
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
PDF tools + QR over MCP: merge, split, rotate, text, metadata, malicious-content scan.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA PDF processing server that extracts text via normal parsing or OCR, and retrieves images from PDF files through the MCP protocol with a built-in web debugger.36-
- FlicenseAqualityNot gradedmaintenanceA Model Context Protocol server that extracts and processes content from PDF documents, providing text extraction, metadata retrieval, page-level processing, and PDF validation capabilities.41-
- AlicenseAqualityCmaintenanceAn MCP server for reading, rendering, and searching PDF files, specifically optimized for LLMs to extract text, tables, and technical diagrams. It enables metadata retrieval, multi-format text extraction, and page-to-image rendering using PyMuPDF.583MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for extracting text from PDF files, supporting local files and URLs.-