PDF Manipulation

You can perform a wide range of PDF edits directly through a Model Context Protocol (MCP) server built for PDF manipulation. This server lets you add or replace text, insert images, manage annotations and form fields, and perform page-level operations like merging, splitting, rotating, cropping, and auto-cropping, all while preserving metadata and producing safe output files with timestamps.

How to use

You connect to the MCP server using an MCP client and issue high-level operations such as adding text, extracting images, or merging PDFs. Start by choosing an available operation, for example to add text to a PDF page, crop pages, or auto-crop all pages to content boundaries. The server creates new output files with timestamps so originals remain intact, and it validates inputs to prevent invalid operations.

How to install

Prerequisites: you need Python 3.10 or newer and a working Python environment with pip.

Option 1: Run with UV (no installation required) so you can start experimenting quickly.

uv run pdf-manipulation-mcp-server

Option 2: Install from PyPI and run the server directly from your system path.

pip install pdf-manipulation-mcp-server

# Run the server
pdf-mcp-server

Option 3: Install from GitHub and run the server from your environment.

pip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git

# Run the server
pdf-mcp-server

Option 4: Clone the project, install in development mode, then run.

# Clone the repository
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# Install in development mode
pip install -e .

# Run the server
pdf-mcp-server

Option 5: Development workflow with UV for dependencies and tests.

# Clone the repository
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# Install dependencies with UV
uv pip install mcp pymupdf

# Test the server
uv run pytest tests/ -v

# Run the server in development
uv run python server.py

Additional content

Configuration and usage notes help you tailor the server to your environment. All operations produce new files with timestamps in the same directory structure as the originals, following the pattern {original_name}_{operation}_{timestamp}.pdf to avoid overwriting sources.

Common troubleshooting tips include ensuring you have the required Python version, installing dependencies with the correct tool (UV or pip), and checking the logs for MCP errors if tools do not appear in the client interface. If UV or Python versions cause issues, install the appropriate version and retry the setup.

Development notes cover the core capabilities: text and image operations, annotations, form fields, page manipulation (merge, combine, split, rotate, delete, crop), auto-cropping, page layout options, and metadata management.

Available tools

pdf_add_text

Add text to a PDF at a specified position with control over font size and color.

pdf_replace_text

Replace existing text within a PDF document.

pdf_add_image

Insert an image into a PDF at a chosen location and size.

pdf_extract_images

Extract all images from a PDF to an output directory.

pdf_add_annotation

Add annotations such as text, highlight, underline, or strikeout to PDF pages.

pdf_add_form_field

Add form fields like text, checkbox, radio, or combobox to a PDF.

pdf_fill_form

Fill in form fields in a PDF with provided values.

pdf_merge_files

Merge multiple PDF files into a single document.

pdf_combine_pages_to_single

Combine multiple pages into a single page with a chosen layout.

pdf_split

Split a PDF into individual pages or specified ranges.

pdf_rotate_page

Rotate a specific page by 90, 180, or 270 degrees.

pdf_delete_page

Delete a page from a PDF.

pdf_crop_page

Crop a page using coordinates with optional bounding box mode.

pdf_auto_crop_page

Automatically crop pages by detecting content boundaries.

pdf_get_info

Retrieve metadata and information about a PDF.

pdf_set_metadata

Set metadata for a PDF.