📄 MCP PDF

A FastMCP server for PDF processing

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

👁 Python 3.11+
👁 FastMCP
👁 License: MIT
👁 PyPI

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

Related MCP server: MCP PDF Reader Server

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 six-term vocabulary (text/checkbox/radio/dropdown/date/signature + button/unknown) shared between AcroForm and XFA tools, so callers don't have to learn two models.

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.

extract_xfa_fields defaults to the zipForm producer profile (Lone Wolf / zipForm Plus — the most common XFA producer in the wild). Pass profile="generic" plus extra_plumbing_patterns / extra_positional_patterns for other producers. The original XFA name appears on every field as the round-trip key for filling. canonical_name appears only on shared fields. canonical_separator chooses _ (snake, default) / . (dotted) / - (kebab). include_design_time_bbox=True opts into best-effort geometry — not authoritative for dynamic XFA (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

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.

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

Optional environment variables:

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/

License

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers