PDF

You have a Python-based MCP server that can fill PDF forms, perform basic editing (merge, extract, rotate, flatten), and extract text with OCR. It works with both native PDF text and OCR when you’re dealing with scanned or image-based documents, making it versatile for form filling and data extraction tasks.

How to use

Run the server locally and connect from your MCP client to perform form filling, page manipulation, and text extraction. The server exposes a set of tools you can invoke through standard MCP client calls to fill forms, clear fields, flatten, merge, split, rotate, insert or remove pages, add and manage annotations and watermarks, and extract text with optional OCR.

How to install

Prerequisites you need before installing: Python and a Python environment, and a client capable of speaking the MCP protocol. Install uv if you do not have it yet, because it helps manage Python environments and dependencies.

curl -Ls https://astral.sh/uv/install.sh | sh

Navigate to the project directory and install Python dependencies. You can use uv to install with a single step or run the project’s Makefile target.

cd /path/to/pdf-mcp-server
uv pip install -r requirements.txt

Alternatively, use the Makefile to install dependencies.

cd /path/to/pdf-mcp-server
make install

For best performance with form flattening, install Poppler.

sudo apt-get install poppler-utils

OCR support is optional and enhances text extraction from scanned PDFs. Install Tesseract if you plan to OCR images, or install the ocr extra.

# macOS
brew install tesseract
pip install pytesseract pillow

# Linux (Ubuntu/Debian)
sudo apt-get install tesseract-ocr
pip install pytesseract pillow

# Or install with OCR extra
pip install -e ".[ocr]"

Run the MCP server

Start the server locally so your MCP client can connect and issue commands.

python -m pdf_mcp.server

Register with Cursor

If you use Cursor as your MCP client, add a local server entry that points to your Python environment and the server module.

{
  "mcpServers": {
    "pdf-handler": {
      "command": "/path/to/pdf-mcp-server/.venv/bin/python",
      "args": ["-m", "pdf_mcp.server"],
      "description": "Local PDF form filling and editing (stdio)"
    }
  }
}

Notes on using the tools

The server exposes a rich set of tools for PDF manipulation and data extraction. You can fill forms, clear fields, flatten, merge, extract pages, rotate pages, annotate, insert and remove text, manage signatures, and work with metadata. All text insert/edit/remove actions are implemented using managed FreeText annotations, which keeps the PDF content streams intact while allowing controlled editing.

Additional topics

OCR and text extraction capabilities let you classify PDFs as searchables, image-based, or hybrid, and provide page-by-page guidance on when to apply OCR. You can extract native text from the PDF text layer for speed or use OCR to retrieve text from images. Utilities also exist to read text blocks with bounding boxes to assist with form-field detection.

If you need to protect edited PDFs, you can encrypt the document after applying the required changes, such as adding a signature image, to prevent further alterations.

Available tools

get_pdf_form_fields

List all form fields in a PDF and return their names and count.

fill_pdf_form

Fill fields in a PDF form with provided data; can optionally flatten the result to remove form fields.

clear_pdf_form_fields

Clear selected form fields while keeping them fillable for subsequent edits.

flatten_pdf

Flatten forms and annotations so form fields become fixed content.

merge_pdfs

Merge multiple PDFs into a single document.

extract_pages

Extract specified pages from a PDF, supporting 1-based indexing and negative indices.

rotate_pages

Rotate specified pages by a multiple of 90 degrees.

add_text_annotation

Insert a FreeText annotation with managed text on a page.

update_text_annotation

Update a managed text annotation by its ID.

remove_text_annotation

Remove a managed text annotation by its ID.

remove_annotations

Remove annotations on given pages, with optional subtype filtering.

insert_pages

Insert all pages from one PDF into another before a target page.

remove_pages

Remove specific pages from a PDF.

insert_text

Insert text via a managed FreeText annotation on a specified page.

edit_text

Edit managed inserted text by its ID.

remove_text

Remove managed inserted text by its ID.

get_pdf_metadata

Return basic metadata for a PDF.

set_pdf_metadata

Set basic metadata fields like title, author, subject, and keywords.

add_text_watermark

Add a simple text watermark or stamp via FreeText annotations.

add_comment

Add a PDF text annotation as a comment on a page.

update_comment

Update a PDF comment by its ID.

remove_comment

Remove a PDF comment by its ID.

add_signature_image

Attach a signature image to a page and return a reference.

update_signature_image

Update or resize an existing signature image.

remove_signature_image

Remove a signature image from a page.

encrypt_pdf

Encrypt and password-protect a PDF after modifications.

detect_pdf_type

Classify a PDF as searchable, image-based, or hybrid, with per-page metrics.

extract_text_native

Extract text using the native PDF text layer for speed.

extract_text_ocr

Extract text with OCR as a fallback or primary method, with engine options.

get_pdf_text_blocks

Extract text blocks with bounding box positions to aid form-field detection.