PDF Manipulation MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PDF Manipulation MCP Server Merge my two PDF files into one document"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PDF Manipulation MCP Server
š This project is entirely based on PyMuPDF - a powerful Python library for PDF manipulation. Please check out the official PyMuPDF documentation to learn more about its extensive capabilities!
A study project implementing a Model Context Protocol (MCP) server that provides comprehensive PDF manipulation capabilities using the official MCP FastMCP framework. This project focuses on direct PDF editing and manipulation features for learning and experimentation purposes.
Quick Start: Run directly with uv run pdf-manipulation-mcp-server (like npx for Node.js packages)
Features
Text Operations: Add, replace, and manipulate text in PDFs
Image Operations: Add images and extract images from PDFs
Annotations: Add various types of annotations (text, highlight, underline, etc.)
Form Fields: Add and fill form fields
Page Manipulation: Merge, split, rotate, delete, and crop pages
Auto-Crop: Automatically detect and crop content boundaries
Page Combination: Combine multiple pages into single pages with various layouts
Metadata: Get and set PDF metadata
Related MCP server: Nutrient Document Engine MCP Server
Quick Start
Prerequisites
Python 3.10+
pip (comes with Python)
š For detailed installation instructions, see INSTALL.md
Installation
Option 1: Run Directly with UV (Like npx)
# Run without installation (fastest)
uv run pdf-manipulation-mcp-serverOption 2: Install from PyPI
# Install the package
pip install pdf-manipulation-mcp-server
# Run the server
pdf-mcp-serverOption 3: Install from GitHub
# Install directly from GitHub
pip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git
# Run the server
pdf-mcp-serverOption 4: Clone and Install Locally
# 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-serverOption 5: Using UV (Development)
# 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
uv run python server.pyAvailable Tools (15 Total)
Text Operations
pdf_add_text- Add text to a PDF at specified positionpdf_replace_text- Replace text in a PDF document
Image Operations
pdf_add_image- Add an image to a PDFpdf_extract_images- Extract all images from a PDF
Annotations
pdf_add_annotation- Add annotations to a PDF (text, highlight, underline, strikeout)
Form Fields
pdf_add_form_field- Add form fields to a PDF (text, checkbox, radio, combobox)pdf_fill_form- Fill form fields in a PDF with values
Page Manipulation
pdf_merge_files- Merge multiple PDF files into onepdf_combine_pages_to_single- Combine multiple pages from a PDF into a single pagepdf_split- Split a PDF into individual pages or page rangespdf_rotate_page- Rotate a page in a PDF (90, 180, 270 degrees)pdf_delete_page- Delete a page from a PDFpdf_crop_page- Crop a page in a PDF with coordinate supportpdf_auto_crop_page- Automatically crop pages by detecting content boundaries
Metadata
pdf_get_info- Get metadata and information about a PDFpdf_set_metadata- Set metadata for a PDF
How to Configure with Cursor IDE
Step 1: Install the Server
Follow the installation steps above to set up the MCP server.
Step 2: Configure Cursor IDE
Add this configuration to your Cursor settings:
Option A: Using an MCP config and uvx:
Create ~/.cursor/mcp_config.json:
{
"mcpServers": {
"pdf-manipulation": {
"command": "uvx",
"args": ["--from", "pdf-manipulation-mcp-server", "pdf-mcp-server"]
}
}
}Option B: Using MCP Config File from a local installation
Create ~/.cursor/mcp_config.json:
{
"mcpServers": {
"pdf-manipulation": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/pdf-manipulation-mcp-server"
}
}
}Option C: Using Cursor Settings UI
Open Cursor Settings (
Cmd+,on Mac,Ctrl+,on Windows/Linux)Search for "MCP" in settings
Add this configuration:
{
"mcp.servers": {
"pdf-manipulation": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/pdf-manipulation-mcp-server"
}
}
}Step 3: Restart Cursor IDE
After adding the configuration, restart Cursor IDE to load the MCP server.
Step 4: Test the Integration
Open a new chat in Cursor
Try these commands:
"Convert this PDF to Markdown"
"Add text to a PDF"
"Extract images from a PDF"
"Merge multiple PDFs"
Usage Examples
Basic PDF Auto-Crop Workflow
# Automatically crop PDF pages to remove margins
result = await pdf_auto_crop_page(
pdf_path="document.pdf",
padding=10.0
)
# Crop specific page with coordinates
result = await pdf_crop_page(
pdf_path="document.pdf",
page_number=0,
x0=50, y0=50, x1=400, y1=300,
coordinate_mode="bbox"
)Adding Text to PDF
result = await pdf_add_text(
pdf_path="document.pdf",
page_number=0,
text="New text content",
x=100,
y=100,
font_size=14,
color=[1, 0, 0] # Red color
)Working with Images
# Add image to PDF
result = await pdf_add_image(
pdf_path="document.pdf",
page_number=0,
image_path="image.png",
x=100,
y=200,
width=200,
height=150
)
# Extract all images from PDF
result = await pdf_extract_images(
pdf_path="document.pdf",
output_dir="extracted_images"
)Page Manipulation
# Merge multiple PDFs
result = await pdf_merge_files(
pdf_paths=["doc1.pdf", "doc2.pdf", "doc3.pdf"]
)
# Combine pages from a single PDF
result = await pdf_combine_pages_to_single(
pdf_path="document.pdf",
page_numbers=[0, 1, 2],
layout="vertical"
)
# Split PDF into individual pages
result = await pdf_split(
pdf_path="document.pdf",
output_dir="split_pages"
)
# Rotate a page
result = await pdf_rotate_page(
pdf_path="document.pdf",
page_number=0,
rotation=90
)Development
Project Structure
pdf-manipulation-mcp-server/
āāā pdf_server.py # Main MCP server implementation
āāā server.py # Entry point for UV
āāā test_mcp_server.py # Test script
āāā pyproject.toml # Project configuration
āāā install.sh # Installation script (Mac/Linux)
āāā install.bat # Installation script (Windows)
āāā README.md # This fileRunning Tests
# Test the MCP server
uv run python test_mcp_server.py
# Run the server
uv run python server.pyDependencies
mcp- Official MCP SDK for Pythonpymupdf- Core PDF manipulation librarypytest- Testing framework (dev dependency)pytest-asyncio- Async testing support (dev dependency)
File Safety
All operations create new files with timestamps to avoid overwriting originals. Output files follow the pattern: {original_name}_{operation}_{timestamp}.pdf
Error Handling
The server includes comprehensive error handling:
Validates PDF files before operations
Checks page numbers and coordinates
Provides clear error messages
Handles missing files gracefully
Catches and reports PyMuPDF exceptions
Troubleshooting
Common Issues
"No tools" in Cursor settings: This is normal! Tools appear in the chat interface, not in settings.
UV not found: Install UV first:
curl -LsSf https://astral.sh/uv/install.sh | shPython version error: UV will automatically install Python 3.11+ if needed.
Dependencies not found: Make sure you're using UV:
uv pip install mcp pymupdf
Debug Mode
To run the server in debug mode:
uv run python server.py --debugContributing
This is a study project, but contributions are welcome! If you'd like to contribute:
Fork the repository
Create a feature branch
Make your changes
Test with
uv run pytest tests/ -vSubmit a pull request
Study Project Notes
This project was created as a learning exercise to explore:
Model Context Protocol (MCP) server development
PDF manipulation using PyMuPDF
FastMCP framework implementation
Automated testing with pytest
Content detection and cropping algorithms
License
This project is open source and available under the MIT License.
Support
For issues and questions:
Check the troubleshooting section above
Review the test output:
uv run python test_mcp_server.pyCheck Cursor logs for MCP errors
Open an issue on GitHub
Available Tools
16 toolspdf_add_annotationC
Add an annotation to a PDF.
Inputs: x (required), y (required), width (required), height (required), +4 more. Returns: result
pdf_add_form_fieldC
Add a form field to a PDF.
Inputs: x (required), y (required), width (required), height (required), +5 more. Returns: result
pdf_add_imageC
Add an image to a PDF.
Inputs: x (required), y (required), width (required), height (required), +3 more. Returns: result
pdf_add_textC
Add text to a PDF at a specified position.
Inputs: x (required), y (required), text (required), pdf_path (required), +3 more. Returns: result
pdf_auto_crop_pageC
Automatically crop a PDF page to remove blank margins by detecting content boundaries.
Inputs: pdf_path (required), padding, page_number. Returns: result
pdf_combine_pages_to_singleC
Combine multiple pages from a PDF into a single page with specified layout.
Inputs: pdf_path (required), layout, output_path, page_numbers. Returns: result
pdf_crop_pageC
Crop a page in a PDF.
Inputs: x0 (required), x1 (required), y0 (required), y1 (required), +3 more. Returns: result
pdf_delete_pageC
Delete a page from a PDF.
Inputs: pdf_path (required), page_number (required). Returns: result
pdf_extract_imagesC
Extract all images from a PDF.
Inputs: pdf_path (required), output_dir. Returns: result
pdf_fill_formB
Fill form fields in a PDF with values.
Inputs: pdf_path (required), field_values (required). Returns: result
pdf_get_infoB
Get metadata and information about a PDF.
Inputs: pdf_path (required). Returns: result
pdf_merge_filesC
Merge multiple PDF files into one combined PDF.
Inputs: pdf_paths (required), output_path. Returns: result
pdf_replace_textC
Replace text in a PDF document.
Inputs: new_text (required), old_text (required), pdf_path (required), page_number. Returns: result
pdf_rotate_pageC
Rotate a page in a PDF.
Inputs: pdf_path (required), rotation (required), page_number (required). Returns: result
pdf_set_metadataC
Set metadata for a PDF.
Inputs: metadata (required), pdf_path (required). Returns: result
pdf_splitB
Split a PDF into individual pages or page ranges.
Inputs: pdf_path (required), output_dir, page_ranges. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 16 tools
Most tools target distinct actions or resources (e.g., add_text vs replace_text, add_image vs extract_images). Some overlap exists between crop_page and auto_crop_page, and between merge_files and combine_pages_to_single, but descriptions clarify the differences.
All tools follow a snake_case pattern with the pdf_ prefix and mostly verb_noun structure (pdf_add_text, pdf_rotate_page). The only deviation is pdf_split, which lacks an explicit object, but the pattern is otherwise consistent.
With 16 tools, the server is at the high end of what is typically well-scoped, but the breadth of PDF manipulation features (text, images, forms, pages, metadata, merging) justifies the count. Each tool covers a distinct need without excessive redundancy.
The tool surface covers the main PDF operations: editing, extraction, merging/splitting, page manipulation, forms, and metadata. Minor gaps exist, such as no explicit page reordering or form flattening, but these are not critical for the core purpose.
Related MCP Connectors
PDF tools for AI agents: validate, extract, merge, split, compress, OCR, sign and redact.
PDF tools for AI agents: inspect, fill, merge, split, rotate, watermark, protect and invoice PDFs.
13 stateless PDF tools for AI agents: merge, split, rotate, compress, watermark, redact, flatten, repair, add page numbers and fill PDF forms. Files are processed in memory and nothing is stored. Part of FreeDailyPro's 211+ MCP tools; trial key with 20,000 calls/month at freedailypro.com/developers.
Generate and read PDFs for AI agents: a generate_pdf and a read_pdf tool, priced per document.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables comprehensive PDF operations including text/image manipulation, annotations, form fields, page merging/splitting/cropping, and metadata management using PyMuPDF.169MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and users to process documents through natural language, supporting PDF operations like text extraction, redaction, splitting, form filling, annotations, and content search.60 npm62MIT
- AlicenseNot gradedqualityDmaintenanceEnables PDF file manipulation including merging, splitting, extracting pages, extracting text, excluding pages, and reordering pages.1MIT
- AlicenseAqualityDmaintenanceEnables PDF processing and analysis including text extraction, metadata retrieval, search, page manipulation, splitting/merging, conversion to images, and form handling.10MIT