PDF MCP Server

MCP server for PDF form filling, editing, OCR text extraction, table extraction, image extraction, link extraction, and batch processing.

Built with Python, pypdf, fillpdf, and pymupdf (AGPL).

Goal: Extract 99% of information from any PDF file, including scanned/image-based documents, and fill any PDF forms.

Status

Quick Start

CI notes

• Dependency Review requires GitHub Dependency Graph to be enabled in the repository settings.

• AI Review is optional and only runs if you add the OPENAI_API_KEY repository secret.

Setup (uv)

1. Install uv if not present:

2. Install dependencies (project root is this folder):

Or use the Makefile:

For best flatten support, install Poppler:

OCR Support (Optional)

For OCR capabilities on scanned/image-based PDFs, install Tesseract:

macOS:

Linux (Ubuntu/Debian):

Additional language packs (optional):

Or install with the ocr extra:

Run the MCP server

(It runs over stdio by default.)

Register with Cursor

Edit ~/.cursor/mcp.json:

Restart Cursor after saving.

Features Overview (51 tools)

Available Tools

Form Handling

• get_pdf_form_fields(pdf_path): list fields and count.

• fill_pdf_form(input_path, output_path, data, flatten=False): fill fields; optional flatten.

• fill_pdf_form_any(input_path, output_path, data, flatten=False): fill standard or non-standard forms using label detection when needed.

• clear_pdf_form_fields(input_path, output_path, fields=None): clear values while keeping fields fillable.

• flatten_pdf(input_path, output_path): flatten forms/annotations.

• create_pdf_form(output_path, fields, page_size=None, pages=1): create a new PDF with AcroForm fields.

• get_form_templates(): list built-in templates for common workflows.

• create_pdf_form_from_template(output_path, template_name): create a form from a built-in template. Note: XFA/LiveCycle forms are not supported; convert to AcroForm or flatten first.

Page Operations

• merge_pdfs(pdf_list, output_path): merge multiple PDFs.

• extract_pages(input_path, pages, output_path): 1-based pages, supports negatives (e.g., -1 = last).

• rotate_pages(input_path, pages, degrees, output_path): degrees must be multiple of 90.

• reorder_pages(input_path, pages, output_path): reorder pages using a 1-based page list.

• insert_pages(input_path, insert_from_path, at_page, output_path): insert pages from another PDF.

• remove_pages(input_path, pages, output_path): remove specific pages.

Annotations & Text

• add_text_annotation(input_path, page, text, output_path, rect=None, annotation_id=None): add FreeText annotation.

• update_text_annotation(input_path, output_path, annotation_id, text, pages=None): update annotation by id.

• remove_text_annotation(input_path, output_path, annotation_id, pages=None): remove annotation by id.

• remove_annotations(input_path, output_path, pages, subtype=None): remove annotations, optionally by subtype.

• redact_text_regex(input_path, output_path, pattern, ...): redact text using a regex pattern.

• add_text_watermark(input_path, output_path, text, ...): add text watermark/stamp.

• add_highlight(input_path, output_path, page, text=None, rect=None): add highlight annotations.

• add_date_stamp(input_path, output_path, ...): add a date stamp.

• add_page_numbers(input_path, output_path, ...): add page numbers as annotations.

• add_bates_numbering(input_path, output_path, ...): add Bates numbering as annotations.

• add_comment / update_comment / remove_comment: PDF comments (sticky notes).

Signatures & Security

• add_signature_image(input_path, output_path, page, image_path, rect): add signature image.

• update_signature_image(...): update or resize signature.

• remove_signature_image(...): remove signature image.

• sign_pdf(input_path, output_path, pfx_path, ...): sign with PKCS#12/PFX, optional timestamp_url, embed_validation_info, allow_fetching, docmdp_permissions.

• sign_pdf_pem(input_path, output_path, key_path, cert_path, ...): sign with PEM key + cert chain, supports timestamping, revocation checks, DocMDP.

• encrypt_pdf(input_path, output_path, user_password, ...): password-protect PDF.

• verify_digital_signatures(pdf_path): verify digital signatures.

Metadata

• get_pdf_metadata(pdf_path, full=False): return document metadata; set full=True for extended info.

• set_pdf_metadata(input_path, output_path, title=None, author=None, ...): set metadata fields.

• sanitize_pdf_metadata(input_path, output_path, ...): remove metadata keys.

Export

• export_pdf(pdf_path, output_path, format="markdown", ...): export text to Markdown or JSON. Formats: "markdown", "json".

OCR and Text Extraction

• detect_pdf_type(pdf_path): analyze PDF to classify as "searchable", "image_based", or "hybrid"; returns page-by-page metrics and OCR recommendation.

• extract_text(pdf_path, engine="auto", pages=None, include_confidence=False, ...): unified text extraction. Engines: "native", "auto", "smart", "ocr", "force_ocr". Set include_confidence=True for word-level confidence scores.

• get_pdf_text_blocks(pdf_path, pages=None): extract text blocks with bounding box positions (useful for form field detection).

• get_ocr_languages(): get available Tesseract languages and installation status. Optional language packs: chi_tra, jpn, kor improve OCR for low-quality scans.

Table Extraction

• extract_tables(pdf_path, pages=None, output_format="list"): extract tables as structured data; format "list" or "dict" (with headers).

Image Extraction

• extract_images(pdf_path, output_dir, pages=None, min_width=50, min_height=50, image_format="png"): extract embedded images to files.

• get_image_info(pdf_path, pages=None): get image metadata (dimensions, format, positions) without extracting.

Form Auto-Detection

• detect_form_fields(pdf_path, pages=None): detect potential form fields in non-AcroForm PDFs using text pattern analysis (labels, checkboxes, underlines).

PII Detection

• detect_pii_patterns(pdf_path, pages=None): detect common PII patterns (email, phone, SSN, credit cards).

Link Extraction

• extract_links(pdf_path, pages=None): extract URLs, hyperlinks, and internal references with type categorization.

PDF Optimization

• optimize_pdf(pdf_path, output_path, quality="medium"): compress PDF; quality: "low" (max compression), "medium", "high".

Barcode/QR Detection

• detect_barcodes(pdf_path, pages=None, dpi=200): detect and decode QR codes, Code128, EAN13, etc. Requires optional pyzbar.

Page Splitting

• split_pdf(pdf_path, output_dir, mode="pages", pages_per_split=1): split PDF by pages or bookmarks. Modes: "pages", "bookmarks".

PDF Comparison

• compare_pdfs(pdf1_path, pdf2_path, compare_text=True, compare_images=False): diff two PDFs, find text and page differences.

Batch Processing

• batch_process(pdf_paths, operation, output_dir=None): process multiple PDFs; operations: "get_info", "extract_text", "extract_links", "optimize".

API Reference

Unified Text Extraction:

• Engines: "native" (fast), "auto" (native→OCR), "smart" (per-page), "ocr"/"tesseract", "force_ocr"

• Set include_confidence=True for word-level confidence scores

Unified Page Splitting:

• Modes: "pages" (by count), "bookmarks" (by table of contents)

Unified Export:

• Formats: "markdown", "json"

Extended Metadata:

Agentic AI (v0.8.0+) with Local VLM Support (v0.9.0+)

LLM-powered tools for intelligent PDF processing. Uses local VLM by default (free, no API costs!) Falls back to Ollama or OpenAI.

• get_llm_backend_info(): Check which LLM backends are available (local, ollama, openai).

• auto_fill_pdf_form(pdf_path, output_path, source_data, backend=None): Intelligently fill form fields with LLM-powered field mapping.

• extract_structured_data(pdf_path, data_type=None, schema=None, ocr_engine="auto", ocr_language="eng", backend=None): Extract structured data using pattern matching or LLM (includes non-LLM passport extraction via MRZ + labels). Use ocr_language for non-English OCR.

• analyze_pdf_content(pdf_path, include_summary=True, detect_entities=True, backend=None): Analyze PDF for document type classification, entity extraction, and summarization.

Backend Priority (v0.9.0+):

1. local (free): Local model server at localhost:8100 using Qwen3-VL

2. ollama (free): Local Ollama models

3. openai (paid): OpenAI API (requires OPENAI_API_KEY)

Start local model server (recommended):

Or use Ollama:

Optional override:

Or use OpenAI (paid):

Example:

Conventions

• Paths should be absolute; outputs are created with parent directories if missing.

• Inputs must exist and be files; errors return { "error": "..." }.

• Form flattening prefers fillpdf+poppler; falls back to a pypdf-only flatten (removes form structures).

• Text insert/edit/remove is implemented via managed FreeText annotations, not by editing PDF content streams.

Smoke tests (manual)

Automated Tests

LLM/Agentic AI Tests (v0.9.2+)

E2E Test Requirements:

• Local VLM: Run ./scripts/run_local_vlm.sh (auto-detects best GPU)

• Ollama: Install with curl -fsSL https://ollama.ai/install.sh | sh, then make install-llm-models

• OpenAI: Set OPENAI_API_KEY environment variable (costs money!)

Full environment setup (one-time):

This handles Python venv, system packages, Ollama, GPU detection, and VLM runner generation for both macOS and WSL/Linux.

Test Coverage

• 273 tests total (includes Tier 1/2 coverage + agentic features + multi-backend + e2e tests)

• All tests pass with Tesseract installed

• 18 tests skip depending on which optional dependencies/backends are available

Agent Extensions (v1.0.1+)

This project includes Agent Skills, Subagents, and Hooks for Cursor IDE integration.

Skills (.cursor/skills/)

Skills are portable packages that teach agents domain-specific tasks. Invoke with /skill-name in Agent chat.

Subagents (.cursor/agents/)

Subagents are specialized AI assistants that handle specific types of work. Invoke with /agent-name or mention naturally.

Hooks (.cursor/hooks.json)

Hooks observe and control agent behavior. This project includes:

Usage:

Development Workflow

• Use feature branches off main and open a PR for review.

• Keep each PR focused on a single tool or capability with tests.

• For larger features, split into small PRs (tool surface, core implementation, tests, docs).

• After merging a PR, delete the feature branch and run git fetch --prune locally to keep branch state clean.

• Portability/migration notes: see PROJECT_MEMO/.

License

GNU AGPL-3.0, see LICENSE.

Changelog

See CHANGELOG.md.