📄 MCP PDF

A FastMCP server for PDF processing

52 tools for text extraction, OCR, tables, forms, XFA, annotations, markdown↔PDF, and more

Works great with MCP Office Tools

What It Does

MCP PDF extracts content from PDFs using multiple libraries with automatic fallbacks. If one method fails, it tries another.

Core capabilities:

• Text extraction via PyMuPDF, pdfplumber, or pypdf (auto-fallback)
• Table extraction via Camelot, pdfplumber, or Tabula (auto-fallback)
• OCR for scanned documents via Tesseract
• Form handling - extract, fill, and create PDF forms
• Document assembly - merge, split, reorder pages
• Annotations - sticky notes, highlights, stamps
• Vector graphics - extract to SVG for schematics and technical drawings
• Format conversion - PDF ↔ Markdown (PDF→MD via PyMuPDF, MD→PDF via pandoc)
• XFA forms - Schema extraction for dynamic Adobe LiveCycle forms that no open-source library can render

Quick Start

# Run from PyPI (one-shot, no permanent install)
uvx mcp-pdf

# Add to Claude Code — note the `--` separator before uvx
claude mcp add pdf-tools -- uvx mcp-pdf

# Include the markdown_to_pdf tool (requires pandoc on host)
claude mcp add pdf-tools -- uvx --from "mcp-pdf[markdown]" mcp-pdf

uvx caches tool installs aggressively. After upgrading to a new release, force a refresh with uvx --refresh mcp-pdf (or uvx --refresh --from "mcp-pdf[markdown]" mcp-pdf if you're using extras).

git clone https://github.com/rsp2k/mcp-pdf
cd mcp-pdf
uv sync

# System dependencies (Ubuntu/Debian)
sudo apt-get install tesseract-ocr tesseract-ocr-eng poppler-utils ghostscript

# For markdown_to_pdf — pick one PDF-engine route:
sudo apt-get install pandoc tectonic                                          # recommended (small)
# or:  sudo apt-get install pandoc texlive-xetex texlive-latex-extra          # full TeX
# or:  sudo apt-get install pandoc && pip install weasyprint                  # skip TeX

# Verify
uv run python examples/verify_installation.py

Tools

Content Extraction

Format Conversion

markdown_to_pdf requires: pip install mcp-pdf[markdown] plus the pandoc binary and at least one PDF engine (xelatex, pdflatex, tectonic, weasyprint, or wkhtmltopdf) on PATH. The tool auto-detects what's available and uses the highest-quality one. Pass pdf_engine= to override or extra_args= for raw pandoc options.

Document Analysis

Forms

Field types are reported in a portable vocabulary (text/checkbox/radio/dropdown/date/signature plus button/unknown) shared between the AcroForm and XFA tools, so callers don't have to learn two models. extract_form_data also returns field_type_raw with the unmerged AcroForm widget type, since listbox and combobox both report as dropdown but differ on free-text entry and multi-select.

XFA Forms (Dynamic Adobe LiveCycle)

Real-estate forms, mortgage forms, government forms — many are dynamic XFA, where the layout + fields live in an XFA program that only Adobe's runtime can render. Every open-source PDF library (PyMuPDF, pdfium, MuPDF, pikepdf) only sees the static "Open in Adobe Reader" placeholder page. These tools recover the form schema instead.

Check detection_failed before trusting is_xfa. Detection has three outcomes: True with an xfa_type, False for a readable non-XFA PDF, and None with detection_failed=True when the file could not be read. A truncated or corrupt form package lands in the third case and gets told so, rather than being reported as a file that simply has no XFA.

extract_xfa_fields defaults to the zipForm producer profile (Lone Wolf / zipForm Plus, the most common XFA producer in the wild), matched case-insensitively. Pass profile="generic" plus extra_plumbing_patterns / extra_positional_patterns for other producers; an unrecognized profile name is an error rather than a silent fallback. Plumbing patterns are substring searches while positional patterns are anchored at the start.

Every response carries success, is_xfa and xfa_type, including failures. Fields land in four categories, not three: shared, positional, other (the default bucket, which holds the majority on non-zipForm producers) and plumbing_fields_dropped. canonical_collisions flags distinct XFA names that canonicalize to the same key, which matters because that key is the cross-form join. The original XFA name is on every field as the round-trip key for filling; canonical_name appears only on shared fields. canonical_separator chooses _ (snake, default), . (dotted) or - (kebab). include_design_time_bbox=True opts into best-effort geometry, page-relative with a top-left origin, and not authoritative for dynamic XFA since subforms reflow at render time.

Permit Forms (Coordinate-Based)

For scanned PDFs or forms without interactive fields. Draws text at (x, y) coordinates.

Requires: pip install mcp-pdf[forms] (adds reportlab dependency)

Document Assembly

Structure Detection

Chapter-aware analysis, for long documents where you want to work a section at a time instead of paging through blindly.

detect_structure writes the full structure to JSON and returns a compact summary plus the path (roughly 1k tokens against ~20k inline). Pass inline=True when you want the whole thing in the response.

Content Analysis

PDF Utilities

Server Introspection

Not PDF tools, so they sit outside the count above. Useful when you want to know what a given install can actually do.

Annotations

How Fallbacks Work

The server tries multiple libraries for each operation:

Text extraction:

1. PyMuPDF (fastest)
2. pdfplumber (better for complex layouts)
3. pypdf (most compatible)

Table extraction:

1. Camelot (best accuracy, requires Ghostscript)
2. pdfplumber (no dependencies)
3. Tabula (requires Java)

If a PDF fails with one library, the next is tried automatically. An engine that raises and one that succeeds but finds no text both fall through, so a page PyMuPDF silently returns nothing for still gets tried by pdfplumber and pypdf.

The response tells you what happened: method_used names the engine that produced the text, and methods_attempted lists the ones skipped and why. When all three come back empty you get method_used: "none" plus an extraction_warning, rather than the emptiness being attributed to whichever engine happened to run last. Naming an engine explicitly (method="pdfplumber") disables the cascade, and a failure then raises instead of falling through.

Token Management

Large PDFs can overflow MCP response limits. The server handles this:

• Automatic chunking splits large documents into page groups
• Table row limits prevent huge tables from blowing up responses
• Summary mode returns structure without full content

# Get first 10 pages
result = await extract_text("huge.pdf", pages="1-10")

# Limit table rows
tables = await extract_tables("data.pdf", max_rows_per_table=50)

# Structure only
tables = await extract_tables("data.pdf", summary_only=True)

URL Processing

PDFs can be fetched directly from HTTPS URLs:

result = await extract_text("https://example.com/report.pdf")

Files are cached locally for subsequent operations.

System Dependencies

Some features require system packages:

Picking a PDF engine for markdown_to_pdf

Pandoc takes markdown → HTML or LaTeX → PDF. The LaTeX path produces the most polished output but needs a TeX install. Trade-offs:

Ubuntu/Debian:

sudo apt-get install tesseract-ocr tesseract-ocr-eng poppler-utils ghostscript default-jre-headless

# For markdown_to_pdf — pick one engine route:

# Option A — tectonic (smallest, downloads packages on demand)
sudo apt-get install pandoc
# tectonic isn't in apt — install via cargo or download static binary:
#   https://tectonic-typesetting.github.io/en-US/install.html

# Option B — full TeX (best quality, large download)
sudo apt-get install pandoc texlive-xetex texlive-latex-extra texlive-fonts-extra

# Option C — weasyprint (skip TeX entirely)
sudo apt-get install pandoc
pip install weasyprint

Arch Linux:

sudo pacman -S tesseract tesseract-data-eng poppler ghostscript jre-openjdk-headless

# For markdown_to_pdf — pick one engine route:

# Option A — tectonic (recommended for new installs, in official repo)
sudo pacman -S pandoc tectonic

# Option B — full TeX (best output, ~500 MB)
sudo pacman -S pandoc texlive-xetex texlive-latexextra texlive-fontsextra

# Option C — weasyprint (skip TeX)
sudo pacman -S pandoc
pip install weasyprint   # or: uv pip install weasyprint

# Option D — wkhtmltopdf (from AUR)
yay -S wkhtmltopdf-static

macOS (Homebrew):

brew install tesseract poppler ghostscript

# For markdown_to_pdf — pick one engine route:

# Option A — tectonic (recommended)
brew install pandoc tectonic

# Option B — full TeX (mactex-no-gui includes the latex-extra equivalent)
brew install pandoc
brew install --cask mactex-no-gui

# Option C — weasyprint
brew install pandoc weasyprint

Optional Extras

The base install stays lean. Heavy or niche dependencies are gated behind extras:

Configuration

All optional. Defaults are tuned for local stdio use (Claude Desktop, Claude Code), which is the common case.

Output-path restriction

MCP_PDF_ALLOWED_PATHS takes a colon-separated list of directories that tools may write into. It is not enforced in stdio mode, which is the default, on the reasoning that a local server writing to the user's own filesystem does not need to be fenced off from it. Enforcement switches on when either of these is set:

If you expose this server over HTTP, set both MCP_TRANSPORT=http and MCP_PDF_ALLOWED_PATHS. Setting the allowlist alone has no effect in stdio mode. And note the framing in CLAUDE.md: application-level path checks are a speed bump, not a boundary. Real isolation comes from running as an unprivileged user in a container with the filesystem it actually needs and nothing more.

XFA limits

Bound the XFA parser against hostile or merely enormous templates. expat caps entity amplification relative to input size, so bounding the input is what bounds the expansion.

Development

# Run tests
uv run pytest

# With coverage
uv run pytest --cov=mcp_pdf

# Format
uv run black src/ tests/

# Lint
uv run ruff check src/ tests/

Versioning

CalVer, YYYY.MM.DD, with a PEP 440 post-release segment for same-day fixes (2026.09.21.1). This package is a thin layer over PyMuPDF, pdfplumber, pypdf, Camelot, Tabula, Tesseract, pandoc and several system binaries, and most surprising behavior traces back to one of those. When a PDF misbehaves, the useful question is "when was this last tested against those?", which a date answers.

Releases before 2026.09.21 used semver. PEP 440 compares the release tuple numerically, so (2026, 9, 21) sorts after (2, 3, 1) and pip install --upgrade works correctly across the switch. See CHANGELOG.md.

License

MIT