# PDF Reader (PDF Agent Stack) [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/shuji-bonji/pdf-reader-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 2944  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pdf-reader-pdf-agent-stack

## Description
Read PDF internals: text, structure, fonts, signatures and tags, with what was not read declared.

## Tools
Capabilities this server exposes over MCP:

- **get_page_count** — 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
- **get_metadata** — 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
- **read_text** — 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.

`/ActualText` replacements (ISO 32000-2 §14.9.4) are resolved, on both of the paths that clause defines: the `/ActualText` of a structure element, and the one in a `Span` marked-content property list — the latter occurs in untagged documents too. So a word carried as ActualText (ligature substitutes, hyphenation fixes) reads here the way a person viewing the page sees it, not in its glyph form.

For **tagged** PDFs, `extract_structured_text` is still the better tool when order matters: it returns text in logical content order (ISO 32000-2 §14.8.2.5), which this tool does not — read_text sorts by coordinate. Tables in tagged PDFs are best read with `extract_tables`.

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.

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". **Omitting it means ALL pages** — on a large document that consumes the whole response budget in one call. Past ~50 pages, search_text first and pass an explicit range here.
  - 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.

Every page also reports how much of its text could be converted to Unicode (ISO 32000-2 §9.10.1): `extracted`, `no_text_layer` (no text-showing operator, image content present — reading it needs OCR or a rendered page), `not_extractable` (a font used here offers no route to Unicode, so text is missing or wrong), or `not_observed` (encrypted or unreadable content stream). An empty result is therefore never by itself evidence that a page has no text.

Two separate readings produce that answer: taking the characters off the page, and observing whether those characters have a route to Unicode. Either can fail on its own, so the response says which of the two was done, under `scope`. When the characters were taken but the observation could not run, the text is still returned and `extractability` is left off the pages — absent is not `extracted`. When the characters could not be taken but the observation ran, `text` is `null` (not `""`, which would say the page has no text) and the per-page observation still tells you whether the page has any text-showing operator at all. Only when neither reading could be done is this an error, and it then names both reasons.

Returns:
  `{ scope, pages }`. `pages` is the extracted text organized by page number, preceded by the extractability tally. 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 }
- **search_text** — 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.

The search runs over the same text `read_text` returns, so `/ActualText` replacements (ISO 32000-2 §14.9.4) match: a word carried as ActualText (ligature substitutes, hyphenation fixes) is found under the spelling a viewer shows, not under its glyph form. Rarely, a page's marked content cannot be aligned with the extracted text and the replacement is left unresolved; when that happens on a search with no hits, the result carries a `note` naming those pages.

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, plus `scope` — which of the two readings behind the answer were done: searching the characters on the page, and observing whether those characters have a route to Unicode (ISO 32000-2 §9.10.1). When the search itself could not run, `totalMatches` and `matches` are `null` rather than `0` and `[]`: "could not search" and "searched and found nothing" are different answers.

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" }
- **read_images** — Extract embedded images from a PDF document as PNG or JPEG files.

Each image is returned as an MCP image content block, so a vision-capable model can look at it directly. A text block lists the metadata for all of them (page, index, size in the file, size returned, colour space, encoded bytes).

These are the image XObjects the page draws, not a picture of the page. A page whose content is vector drawing, or whose text is what you want to see, is not covered by this tool.

Response size is bounded: at most 4 MB of encoded image data per call. Images beyond the budget are named in the text block with the reason and are not returned — nothing is dropped silently. A 200 dpi A4 scan is ~11.6 MB of pixels on its own, so pass `pages`, `max_width` or `max_height` when working with scans.

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". **Omitting it means ALL pages** — on an image-heavy document that exhausts the byte budget immediately. Name the pages you need.
  - format ('png' | 'jpeg', optional): Output encoding. Default 'png' (lossless). 'jpeg' is smaller and composites alpha over white.
  - quality (1-100, optional): JPEG quality. Ignored for PNG.
  - max_width (number, optional): Downscale images wider than this (area average). Never enlarges.
  - max_height (number, optional): Downscale images taller than this.

Returns:
  A text block with the metadata table and any omissions, then one image content block per returned image.

Examples:
  - Extract all images: { file_path: "/path/to/doc.pdf" }
  - A scanned page, small enough to look at: { file_path: "/path/to/scan.pdf", pages: "1", max_width: 1200, format: "jpeg" }
- **read_url** — Fetch a PDF from a URL and extract its text content. Text is ALL this tool returns — see the scope note below.

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.

**Scope (#25):** the fetched bytes are discarded after extraction; this tool deliberately does not save them. Every other tool of this server takes a `file_path`, so to use search_text, inspect_structure, extract_tables, render_page or anything else on a URL's PDF, download the file to local disk FIRST (with whatever fetch capability the calling environment has) and pass its path. This keeps every tool of this server read-only with respect to the file system — writing files is not a reader's job. read_url exists for the one-shot case: "what does the document at this URL say?"

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:
  `{ scope, pages }`, the same shape as read_text: `pages` is the extracted text by page number, and `scope` says which of the two readings behind it were done — taking the characters off the page, and observing whether those characters have a route to Unicode (ISO 32000-2 §9.10.1). Either can fail on its own; only when neither could be done is this an error, and it then names both reasons.

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 }
- **render_page** — Rasterise pages of a PDF to PNG or JPEG images, returned as MCP image content blocks.

This is the tool for documents whose text cannot be read as text: pages `read_text` reports as `no_text_layer` or `not_extractable`, vector drawings, forms, handwriting, stamps. It draws the PAGE — everything on it — where `read_images` only extracts the image XObjects a page happens to embed.

Rendering uses PDFium compiled to WebAssembly (optional dependency `@hyzyla/pdfium`). Note this is a different engine from the pdf.js this server reads text with; where their behaviour on a damaged file differs, neither output is evidence about the other. If the dependency is not installed, this tool says so and every other tool works normally.

`pages` is required — rendering is the most expensive operation here, and "all pages" of a large scan should be a decision, not a default. The response carries at most 4 MB of encoded images; pages past the budget are named with the reason, not dropped.

Args:
  - file_path (string): Absolute path to a local PDF file
  - pages (string, REQUIRED): Page range: "1-3", "5", "1,3,5-7".
  - dpi (36-600, optional): Density, default 150. 150 reads well; 300 for small print.
  - max_width (number, optional): Pixel-width cap; wins over dpi when smaller.
  - format ('png' | 'jpeg', optional): Default 'png'. 'jpeg' is usually right for scans.
  - quality (1-100, optional): JPEG quality.

Returns:
  A text block with per-page metadata (point size, pixel size, effective dpi, bytes) and any omissions, then one image content block per rendered page.

Rasterising a page can take unbounded time — a tiling pattern (ISO 32000-2 §8.7.3.1) whose `/XStep` or `/YStep` is a near-zero magnitude asks for an astronomical number of tiles, and the clause forbids only zero. Each page therefore gets 20 seconds (`PDF_READER_RENDER_TIMEOUT_MS` overrides it); the rendering runs off the main thread, so a page that does not finish is stopped and named in the omissions rather than taking the server down with it. The pages rendered before it are still returned, and the pages after it are reported separately as not attempted — "could not be rendered" and "never started" are different answers.

Examples:
  - A scanned page: { file_path: "/path/to/scan.pdf", pages: "1", format: "jpeg" }
  - A diagram at high detail: { file_path: "/path/to/doc.pdf", pages: "3", dpi: 300 }
- **summarize** — 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')

`hasText` is decided from page 1's preview and cannot say *why* text is absent. `textExtractability` answers that over every page (ISO 32000-2 §9.10.1): `extracted`, `no_text_layer` (image content, no text-showing operator — the page needs OCR or a rendered image), `not_extractable` (a font used offers no route to Unicode), or `not_observed` (encrypted or unreadable content stream). `unreadablePages` lists the pages that are not `extracted`, with the reason.

`declaredConformance` is what the XMP packet (ISO 32000-2 §14.3.2) declares — PDF/A (`pdfaid`), PDF/UA (`pdfuaid`) and the W3C TDMRep rights statement (`tdm`) — as written. A PDF/UA declaration is the author's claim that the structure tree is complete, which is the cue to read through it rather than infer reading order; it is not a verdict (that is pdf-verify-mcp validate_conformance). All-null blocks mean the catalog has no /Metadata; `null` means the packet could not be read (see `scope`).

The summary ends with a `next` list: tool suggestions derived from the observations themselves (hasText false → render_page; PDF/UA declared or tagged → extract_structured_text / extract_tables; large page count → search_text before read_text). Each line names the observation it follows from; nothing is enforced and no ordering is implied.

Returns:
  Summary including: page count, PDF version, file size, tagged/encrypted/signature flags, text presence, per-document text extractability, the pages that are not fully extractable, image count, a text preview from page 1, and the `next` suggestions.

  Five separate readings produce that summary — the document information, the text of page 1, the image count, the extractability observation, and the XMP declarations — and any of them can fail on its own. `scope` says which were done. A field whose reading did not happen is `null`, never `0`, `false` or `""`: "not read" and "read and found nothing" are different answers, and `next` stays silent about any premise that was not observed.

Examples:
  - Quick overview: { file_path: "/path/to/doc.pdf" }
  - Machine-readable: { file_path: "/path/to/doc.pdf", response_format: "json" }
- **inspect_structure** — 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 COS types), page tree info (page count, MediaBox samples), object statistics, and encryption status.

Object statistics report three separate counts:
  - byType: the COS type of each indirect object (ISO 32000-2 §7.3) — one of
    dict, stream, array, name, string, integer, real, boolean, null, ref
  - byDocType: the /Type of each dictionary (Catalog, Pages, Page, Font, ObjStm, XRef, ...)
  - unreadable: objects the cross-reference table names but that could not be read.
    This is counted apart from totalObjects: 0 means "every object was read", not "nothing was checked".

Examples:
  - Examine document catalog for structural features
  - Count PDF objects and streams
  - Check page dimensions across the document
- **inspect_catalog** — List the document-level components hanging off the catalog dictionary (ISO 32000-2 §7.7.2, Table 29) — the parts of a PDF that are not page content and that page-oriented readers drop: bookmarks, layers, attachments, the XMP packet, and the actions that run when the document is opened.

Args:
  - file_path (string): Absolute path to a local PDF file
  - max_outline_items (integer, 1-500, default 50): how many bookmark items to list (count and depth cover the whole tree)
  - include_xmp (boolean, default false): also return the XMP packet text (capped at 64 KiB)
  - response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns, per entry:
  - outlines (/Outlines, §12.3.3): item count, depth, and the first items with title and target page
  - optionalContent (/OCProperties, §8.11.4): every layer's /Name, and the default configuration's BaseState / ON / OFF counts
  - embeddedFiles (/Names → /EmbeddedFiles, §7.7.4 / §7.11.4): file name, MIME type, size, /AFRelationship, description
  - associatedFiles (/AF, §14.13): count at document level
  - names: counts of the /Dests and /JavaScript name trees (document-level ECMAScript runs on open, §12.6.4.17)
  - metadata (/Metadata, §14.3.2): packet size, namespaces present, and the DECLARED values of pdfaid:*, pdfuaid:part and the W3C TDMRep tdm:reservation / tdm:policy
  - openAction (/OpenAction) and additionalActions (/AA, Table 200): action type (/S), target page or file or URI, whether /JS is present, length of the /Next chain
  - collection (/Collection, §12.3.5): whether the document is a portfolio

Each entry distinguishes { status: "absent" } (the catalog has no such key — an observed fact) from { status: "unreadable", reason } (the key is there but its value could not be reached). An encrypted document whose key cannot be derived reports every entry as unreadable, never as absent.

This tool reports what is written. A pdfuaid:part declaration is a claim about the structure tree, not a verdict on it (that is pdf-verify-mcp validate_conformance); tdm:reservation is the rights holder's statement, and whether to honour it is the caller's decision; an action with /JS is reported, not judged.

Examples:
  - Find out whether a document carries attachments, layers or bookmarks before deciding how to read it
  - Read the XMP declarations (PDF/A, PDF/UA, TDMRep) that get_metadata, which reads the Info dictionary, does not see
  - See what a document will execute when opened (/OpenAction, /AA, document-level JavaScript)
- **inspect_tags** — 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
- **inspect_fonts** — 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
- **inspect_annotations** — 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)
- **inspect_signatures** — 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
- **extract_tables** — Extract every `<Table>` subtree from a Tagged PDF as a structured row/cell list,
optionally rendered as Markdown tables.

How it works: walks the document's StructTreeRoot depth-first (the same walker
as `extract_structured_text` / `inspect_tags`) 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).

A Table that continues across a page break is ONE table (ISO 32000-2 §14.8.2.5
NOTE 2) — `pages` is an array, and a table touching the requested page range is
returned whole. Cell text honours `/ActualText` replacements (§14.9.4).

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
  `## Table N — Page(s) …` section per table with a GFM table.

  JSON — `{ isTagged, tables: [{ pages, index, headerRows, bodyRows, footerRows }],
  totalTables, pagesScanned, note? }`. `index` is the table's 1-based position
  in logical content order, document-wide.

Limitations:
  - Untagged PDFs return an empty result and a `note`.
  - colspan/rowspan are not honoured (cells are listed in source order).
  - Nested tables are not emitted separately (their text appears in the outer cell).

Examples:
  - Pull 新旧対照表 from a kaisei tsutatsu PDF for diffing
  - Convert 帳票 (form template) tables into structured data
- **extract_structured_text** — Extract a tagged PDF's text in logical content order, with each piece labelled by its structure type.

This answers "what is the text of the H1?" — which read_text (flat, coordinate order),
inspect_tags (structure, no text) and extract_tables (text, tables only) each cannot.

Args:
  - file_path (string): Absolute path to a local PDF file
  - pages (string, optional): Page range ("1-5", "3", "1,3,5-7"). Omit for all pages.
    An element that touches the range is returned whole, even if it continues outside it.
  - roles (string[], optional): Structure types to include, e.g. ["H1","H2"] for an outline
  - include_bbox (boolean): Also report where each element is drawn (default: false)
  - response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns:
  isTagged, the document language, and a flat list of elements in logical content order.
  Each element has: role, depth (nesting; top level is 0), text, pages, and optionally
  alt / label / rows / boxes / boxNote.

  `scope` says which of the two readings behind that answer were done — reading the structure tree, and observing whether the characters under it have a route to Unicode (ISO 32000-2 §9.10.1). When the structure tree could not be read, `isTagged` and `elements` are `null` rather than `false` and `[]`: "not read" and "read and found no tags" are different answers.

  The list is flat with a depth field rather than nested — a depth-first pre-order plus
  depth encodes the tree exactly, so nothing is lost. Table is the exception and carries
  rows, because a table is two-dimensional and depth cannot express "row 2, column 3".

Key properties:
  - Order is a depth-first traversal of the document's structure tree, which is how
    ISO 32000-2 §14.8.2.5 defines logical content order.
  - An element that spans pages stays ONE element (pages is an array). A paragraph
    split across a page break is returned as one paragraph, not two.
  - ActualText replaces the glyphs when present (§14.9.4: "a replacement, not a
    description"). Alt is reported separately in alt and never as text — it describes
    content that has no text (§14.9.3), so it must not leak into the body.
  - Lbl (a list bullet or number) is reported in label, not mixed into text.
  - Artifacts (page numbers, running heads) are excluded: §14.8.2.5 NOTE 3 puts them
    outside the logical content order.

With include_bbox (answers "where is this paragraph?", so an annotation can be placed on it):
  Each element gains boxes — ONE RECTANGLE PER PAGE, because an element that spans pages
  has no single rectangle. Each is { page, rect: {x1,y1,x2,y2}, basis } in PDF default user
  space (origin bottom-left, pt, already normalised), which is exactly what pdf-writer-mcp
  add_annotation takes: no coordinate system has to be reinterpreted in between. /Rotate and
  a shifted /CropBox do not affect it.

  basis says how strong the claim is, and the two are not the same kind of claim:
    - layout-attribute-bbox — the /BBox the file DECLARES for the element (ISO 32000-2
      Table 379). A statement by the producer about its own geometry, reported as-is.
      This is the only source for content that has no text.
    - text-extent — MEASURED from the text the element owns: baseline origin plus the
      font's ascent/descent. That is the line box, not the glyph outlines. Images and
      vector drawings contribute nothing to it.

  When a declared /BBox does not cover the text measured inside it, that disagreement is
  reported in boxNote rather than smoothed over.

  An element with no rectangle has no boxes and carries boxNote saying why — a Figure
  holding one image is the usual case (§14.8.4.8.5: such an element "should have a BBox
  attribute"). Absent is not zero-sized, and neither is guessed at.

Untagged PDFs return isTagged: false with a reason and no elements. Nothing is guessed
from coordinates — §14.8.2.5 NOTE 1 is explicit that page order need not match logical
order, so a guess could not be trusted. To add a structure scaffold, use pdf-writer-mcp
ensure_tagged and retry.

Examples:
  - Extract a document outline: { file_path: "/doc.pdf", roles: ["H1","H2","H3"] }
  - Get content for reflow / conversion, structure preserved: { file_path: "/doc.pdf" }
  - Read the text of a specific section's pages: { file_path: "/doc.pdf", pages: "4-6" }
  - Find where to put an annotation:
    { file_path: "/doc.pdf", roles: ["P"], include_bbox: true } → hand a box straight to
    pdf-writer-mcp add_annotation. To go the other way, from an object number a diff
    reported to a rectangle, use locate_objects.
- **locate_objects** — Report where the given objects sit on the page.

Bridges "which object" to "which coordinates": pdf-verify-mcp's verify_integrity names the objects an incremental update changed, and pdf-writer-mcp's add_annotation wants a page number and a rectangle. The rectangle is returned in PDF user space (origin bottom-left, pt, x1 < x2 and y1 < y2 — ISO 32000-1 §7.9.5 normalised form), which is exactly what add_annotation takes.

Args:
  - file_path (string): Absolute path to a local PDF file
  - object_numbers (number[]): Object numbers to locate, e.g. [25, 27]
  - response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns:
  Per object: whether it exists, its /Type and /Subtype, and the places it occupies, each with the basis the coordinates rest on:
  - annotation-rect — the object's own /Rect. Exact.
  - page-box — the object is a page; the rectangle is its crop/media box.
  - page-content-stream — the object draws the page; the rectangle is the WHOLE page, not the part that changed.
  - page-resource — a font, image or colour space used by the page. No rectangle exists for it.

Limits (observations, not judgements):
  - Narrowing a content stream to the paragraph that moved needs a content-stream walk with graphics state; this tool does not do it and says so rather than inventing a rectangle.
  - An object that does not exist (freed by a later revision) is returned with found: false — not as "no coordinates".
  - In an encrypted document, coordinates and types are still reliable (numbers and names are not encrypted, ISO 32000-1 §7.6.2) but field names are reported as null instead of mojibake.

Examples:
  - Turn verify_integrity's "obj 27 was added after signing" into a page and rectangle
  - Find which page a changed form field widget is on before annotating it
- **compare_structure** — 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.

  The comparison needs both files, so an unreadable file is an error — but the error names which of the two could not be read, and says that the other one was fine.

Examples:
  - Compare two versions of the same document
  - Verify structural consistency across PDF exports
  - Identify differences in PDF generation pipelines

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What PDF Reader (PDF Agent Stack) does

PDF Reader (PDF Agent Stack) exposes read-only PDF analysis through MCP. It works primarily with absolute paths to local PDF files and can inspect both visible content and the objects behind it. Its coverage ranges from lightweight page counting to tagged-content extraction, catalog inspection, font inventories, annotation analysis, signature-field inspection, and structural comparison between two documents.

The server distinguishes information that was read successfully from information that could not be observed. Text extraction reports per-page states such as `extracted`, `no_text_layer`, `not_extractable`, and `not_observed`, so an empty result is not automatically treated as an empty page. Responses also use scope information to identify which readings completed.

## How it works

`read_text` extracts pages in coordinate-based order, sorting from top to bottom and then left to right. It resolves `/ActualText` replacements and can reorder untagged multi-column documents with `split_columns`. For Japanese form-style PDFs, `compact_whitespace` collapses repeated whitespace, including fullwidth spaces. Tagged documents have a separate path: `extract_structured_text` follows the structure tree's logical order and preserves roles, depth, labels, page spans, and optional bounding boxes.

Use `search_text` before extracting a large document when only selected passages are needed. It searches the same text representation as `read_text` and returns page numbers, matched text, and surrounding context. `read_url` downloads an HTTP or HTTPS PDF for text extraction, then discards the bytes; it does not create a local file for other tools.

`render_page` rasterizes selected pages through the optional PDFium WebAssembly dependency. It is intended for scans, handwriting, forms, vector drawings, stamps, and pages whose text layer cannot be read. `read_images` instead returns embedded image objects, not complete rendered pages. Both image-producing tools cap encoded response data at 4 MB and identify omissions.

## Setup and configuration

The published package is `@shuji-bonji/pdf-reader-mcp`. It is designed to run wherever `npx` runs and uses a standard MCP server arrangement. Claude Code is named by the project, and the server can be used by MCP clients that support standard server connections.

Rendering requires the optional `@hyzyla/pdfium` dependency. Without it, `render_page` reports that the dependency is unavailable while the other tools continue to work. Rendering uses a 20-second per-page timeout by default; `PDF_READER_RENDER_TIMEOUT_MS` overrides that value. The `pages` argument is required for `render_page`, and specifying page ranges is advisable for large text or image-heavy documents.

## Tools and capabilities

- Count pages and extract document metadata, including PDF version, dates, flags, and file size.
- Read or search text with page ranges, JSON or Markdown output, column handling, and extractability reporting.
- Fetch a remote PDF for text-only extraction with `read_url`.
- Extract embedded images or render complete pages as MCP image blocks.
- Summarize a document using metadata, page-one preview, image count, extractability, and suggested next tools.
- Inspect catalogs, object statistics, tags, fonts, annotations, signature fields, and document-level actions.
- Extract logical tagged text and tagged tables, including optional element coordinates.
- Map object numbers to page locations and compare structural properties and fonts across two PDFs.

## Limitations and notes

The server reports PDF contents and structure; it does not perform cryptographic signature verification or PDF/A and PDF/UA conformance validation. Signature inspection covers field structure, signer details, and signing metadata only. Tagged-table extraction returns no table rows for untagged PDFs, does not apply `rowspan` or `colspan`, and does not emit nested tables separately.

`read_text` uses coordinate order rather than logical structure order, so tagged PDFs should use `extract_structured_text` when document order matters. Untagged PDFs cannot provide trusted logical order. `render_page` is expensive and can omit pages that exceed the response budget or rendering timeout, while separately identifying pages that were never attempted.

_Full upstream README: https://allmcps.com/mcp/pdf-reader-pdf-agent-stack/readme_