# PDF Manipulation MCP Server
> **📚 This project is entirely based on [PyMuPDF](https://pymupdf.readthedocs.io/) - 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
## Quick Start
### Prerequisites
- Python 3.10+
- pip (comes with Python)
> **📖 For detailed installation instructions, see [INSTALL.md](INSTALL.md)**
### Installation
**Option 1: Run Directly with UV (Like npx)**
```bash
# Run without installation (fastest)
uv run pdf-manipulation-mcp-server
```
**Option 2: Install from PyPI**
```bash
# Install the package
pip install pdf-manipulation-mcp-server
# Run the server
pdf-mcp-server
```
**Option 3: Install from GitHub**
```bash
# Install directly from GitHub
pip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git
# Run the server
pdf-mcp-server
```
**Option 4: Clone and Install Locally**
```bash
# 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: Using UV (Development)**
```bash
# 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.py
```
## Available Tools (15 Total)
### Text Operations
- **`pdf_add_text`** - Add text to a PDF at specified position
- **`pdf_replace_text`** - Replace text in a PDF document
### Image Operations
- **`pdf_add_image`** - Add an image to a PDF
- **`pdf_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 one
- **`pdf_combine_pages_to_single`** - Combine multiple pages from a PDF into a single page
- **`pdf_split`** - Split a PDF into individual pages or page ranges
- **`pdf_rotate_page`** - Rotate a page in a PDF (90, 180, 270 degrees)
- **`pdf_delete_page`** - Delete a page from a PDF
- **`pdf_crop_page`** - Crop a page in a PDF with coordinate support
- **`pdf_auto_crop_page`** - Automatically crop pages by detecting content boundaries
### Metadata
- **`pdf_get_info`** - Get metadata and information about a PDF
- **`pdf_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`:
```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`:
```json
{
"mcpServers": {
"pdf-manipulation": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/pdf-manipulation-mcp-server"
}
}
}
```
**Option C: Using Cursor Settings UI**
1. Open Cursor Settings (`Cmd+,` on Mac, `Ctrl+,` on Windows/Linux)
2. Search for "MCP" in settings
3. Add this configuration:
```json
{
"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
1. Open a new chat in Cursor
2. 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
```python
# 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
```python
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
```python
# 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
```python
# 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 file
```
### Running Tests
```bash
# Test the MCP server
uv run python test_mcp_server.py
# Run the server
uv run python server.py
```
### Dependencies
- **`mcp`** - Official MCP SDK for Python
- **`pymupdf`** - Core PDF manipulation library
- **`pytest`** - 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
1. **"No tools" in Cursor settings**: This is normal! Tools appear in the chat interface, not in settings.
2. **UV not found**: Install UV first:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
3. **Python version error**: UV will automatically install Python 3.11+ if needed.
4. **Dependencies not found**: Make sure you're using UV:
```bash
uv pip install mcp pymupdf
```
### Debug Mode
To run the server in debug mode:
```bash
uv run python server.py --debug
```
## Contributing
This is a study project, but contributions are welcome! If you'd like to contribute:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with `uv run pytest tests/ -v`
5. Submit 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:
1. Check the troubleshooting section above
2. Review the test output: `uv run python test_mcp_server.py`
3. Check Cursor logs for MCP errors
4. Open an issue on GitHub
Raw data
{
"_id": null,
"home_page": null,
"name": "pdf-manipulation-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "manipulation, mcp, pdf, server, study",
"author": null,
"author_email": "Andr\u00e9 da Silva Medeiros <andr3medeiros@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/35/cb/91b47dcf7aabbe79e222b216405e6a71c2ea129ca5de541df9ca508a3399/pdf_manipulation_mcp_server-0.1.2.tar.gz",
"platform": null,
"description": "# PDF Manipulation MCP Server\n\n> **\ud83d\udcda This project is entirely based on [PyMuPDF](https://pymupdf.readthedocs.io/) - a powerful Python library for PDF manipulation. Please check out the official PyMuPDF documentation to learn more about its extensive capabilities!**\n\nA 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.\n\n**Quick Start:** Run directly with `uv run pdf-manipulation-mcp-server` (like npx for Node.js packages)\n\n## Features\n\n- **Text Operations**: Add, replace, and manipulate text in PDFs\n- **Image Operations**: Add images and extract images from PDFs\n- **Annotations**: Add various types of annotations (text, highlight, underline, etc.)\n- **Form Fields**: Add and fill form fields\n- **Page Manipulation**: Merge, split, rotate, delete, and crop pages\n- **Auto-Crop**: Automatically detect and crop content boundaries\n- **Page Combination**: Combine multiple pages into single pages with various layouts\n- **Metadata**: Get and set PDF metadata\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.10+ \n- pip (comes with Python)\n\n> **\ud83d\udcd6 For detailed installation instructions, see [INSTALL.md](INSTALL.md)**\n\n### Installation\n\n**Option 1: Run Directly with UV (Like npx)**\n\n```bash\n# Run without installation (fastest)\nuv run pdf-manipulation-mcp-server\n```\n\n**Option 2: Install from PyPI**\n\n```bash\n# Install the package\npip install pdf-manipulation-mcp-server\n\n# Run the server\npdf-mcp-server\n```\n\n**Option 3: Install from GitHub**\n\n```bash\n# Install directly from GitHub\npip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git\n\n# Run the server\npdf-mcp-server\n```\n\n**Option 4: Clone and Install Locally**\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/pdf-manipulation-mcp-server.git\ncd pdf-manipulation-mcp-server\n\n# Install in development mode\npip install -e .\n\n# Run the server\npdf-mcp-server\n```\n\n**Option 5: Using UV (Development)**\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/pdf-manipulation-mcp-server.git\ncd pdf-manipulation-mcp-server\n\n# Install dependencies with UV\nuv pip install mcp pymupdf\n\n# Test the server\nuv run pytest tests/ -v\n\n# Run the server\nuv run python server.py\n```\n\n## Available Tools (15 Total)\n\n### Text Operations\n- **`pdf_add_text`** - Add text to a PDF at specified position\n- **`pdf_replace_text`** - Replace text in a PDF document\n\n### Image Operations\n- **`pdf_add_image`** - Add an image to a PDF\n- **`pdf_extract_images`** - Extract all images from a PDF\n\n### Annotations\n- **`pdf_add_annotation`** - Add annotations to a PDF (text, highlight, underline, strikeout)\n\n### Form Fields\n- **`pdf_add_form_field`** - Add form fields to a PDF (text, checkbox, radio, combobox)\n- **`pdf_fill_form`** - Fill form fields in a PDF with values\n\n### Page Manipulation\n- **`pdf_merge_files`** - Merge multiple PDF files into one\n- **`pdf_combine_pages_to_single`** - Combine multiple pages from a PDF into a single page\n- **`pdf_split`** - Split a PDF into individual pages or page ranges\n- **`pdf_rotate_page`** - Rotate a page in a PDF (90, 180, 270 degrees)\n- **`pdf_delete_page`** - Delete a page from a PDF\n- **`pdf_crop_page`** - Crop a page in a PDF with coordinate support\n- **`pdf_auto_crop_page`** - Automatically crop pages by detecting content boundaries\n\n### Metadata\n- **`pdf_get_info`** - Get metadata and information about a PDF\n- **`pdf_set_metadata`** - Set metadata for a PDF\n\n## How to Configure with Cursor IDE\n\n### Step 1: Install the Server\n\nFollow the installation steps above to set up the MCP server.\n\n### Step 2: Configure Cursor IDE\n\nAdd this configuration to your Cursor settings:\n\n**Option A: Using an MCP config and uvx:**\n\nCreate `~/.cursor/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pdf-manipulation\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"pdf-manipulation-mcp-server\", \"pdf-mcp-server\"]\n }\n }\n}\n```\n**Option B: Using MCP Config File from a local installation**\n\nCreate `~/.cursor/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pdf-manipulation\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"server.py\"],\n \"cwd\": \"/path/to/pdf-manipulation-mcp-server\"\n }\n }\n}\n```\n\n**Option C: Using Cursor Settings UI**\n1. Open Cursor Settings (`Cmd+,` on Mac, `Ctrl+,` on Windows/Linux)\n2. Search for \"MCP\" in settings\n3. Add this configuration:\n\n```json\n{\n \"mcp.servers\": {\n \"pdf-manipulation\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"server.py\"],\n \"cwd\": \"/path/to/pdf-manipulation-mcp-server\"\n }\n }\n}\n```\n\n### Step 3: Restart Cursor IDE\n\nAfter adding the configuration, restart Cursor IDE to load the MCP server.\n\n### Step 4: Test the Integration\n\n1. Open a new chat in Cursor\n2. Try these commands:\n - \"Convert this PDF to Markdown\"\n - \"Add text to a PDF\"\n - \"Extract images from a PDF\"\n - \"Merge multiple PDFs\"\n\n## Usage Examples\n\n### Basic PDF Auto-Crop Workflow\n\n```python\n# Automatically crop PDF pages to remove margins\nresult = await pdf_auto_crop_page(\n pdf_path=\"document.pdf\",\n padding=10.0\n)\n\n# Crop specific page with coordinates\nresult = await pdf_crop_page(\n pdf_path=\"document.pdf\",\n page_number=0,\n x0=50, y0=50, x1=400, y1=300,\n coordinate_mode=\"bbox\"\n)\n```\n\n### Adding Text to PDF\n\n```python\nresult = await pdf_add_text(\n pdf_path=\"document.pdf\",\n page_number=0,\n text=\"New text content\",\n x=100,\n y=100,\n font_size=14,\n color=[1, 0, 0] # Red color\n)\n```\n\n### Working with Images\n\n```python\n# Add image to PDF\nresult = await pdf_add_image(\n pdf_path=\"document.pdf\",\n page_number=0,\n image_path=\"image.png\",\n x=100,\n y=200,\n width=200,\n height=150\n)\n\n# Extract all images from PDF\nresult = await pdf_extract_images(\n pdf_path=\"document.pdf\",\n output_dir=\"extracted_images\"\n)\n```\n\n### Page Manipulation\n\n```python\n# Merge multiple PDFs\nresult = await pdf_merge_files(\n pdf_paths=[\"doc1.pdf\", \"doc2.pdf\", \"doc3.pdf\"]\n)\n\n# Combine pages from a single PDF\nresult = await pdf_combine_pages_to_single(\n pdf_path=\"document.pdf\",\n page_numbers=[0, 1, 2],\n layout=\"vertical\"\n)\n\n# Split PDF into individual pages\nresult = await pdf_split(\n pdf_path=\"document.pdf\",\n output_dir=\"split_pages\"\n)\n\n# Rotate a page\nresult = await pdf_rotate_page(\n pdf_path=\"document.pdf\",\n page_number=0,\n rotation=90\n)\n```\n\n## Development\n\n### Project Structure\n\n```\npdf-manipulation-mcp-server/\n\u251c\u2500\u2500 pdf_server.py # Main MCP server implementation\n\u251c\u2500\u2500 server.py # Entry point for UV\n\u251c\u2500\u2500 test_mcp_server.py # Test script\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 install.sh # Installation script (Mac/Linux)\n\u251c\u2500\u2500 install.bat # Installation script (Windows)\n\u2514\u2500\u2500 README.md # This file\n```\n\n### Running Tests\n\n```bash\n# Test the MCP server\nuv run python test_mcp_server.py\n\n# Run the server\nuv run python server.py\n```\n\n### Dependencies\n\n- **`mcp`** - Official MCP SDK for Python\n- **`pymupdf`** - Core PDF manipulation library\n- **`pytest`** - Testing framework (dev dependency)\n- **`pytest-asyncio`** - Async testing support (dev dependency)\n\n## File Safety\n\nAll operations create new files with timestamps to avoid overwriting originals. Output files follow the pattern: `{original_name}_{operation}_{timestamp}.pdf`\n\n## Error Handling\n\nThe server includes comprehensive error handling:\n- Validates PDF files before operations\n- Checks page numbers and coordinates\n- Provides clear error messages\n- Handles missing files gracefully\n- Catches and reports PyMuPDF exceptions\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"No tools\" in Cursor settings**: This is normal! Tools appear in the chat interface, not in settings.\n\n2. **UV not found**: Install UV first:\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n3. **Python version error**: UV will automatically install Python 3.11+ if needed.\n\n4. **Dependencies not found**: Make sure you're using UV:\n ```bash\n uv pip install mcp pymupdf\n ```\n\n### Debug Mode\n\nTo run the server in debug mode:\n\n```bash\nuv run python server.py --debug\n```\n\n## Contributing\n\nThis is a study project, but contributions are welcome! If you'd like to contribute:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test with `uv run pytest tests/ -v`\n5. Submit a pull request\n\n## Study Project Notes\n\nThis project was created as a learning exercise to explore:\n- Model Context Protocol (MCP) server development\n- PDF manipulation using PyMuPDF\n- FastMCP framework implementation\n- Automated testing with pytest\n- Content detection and cropping algorithms\n\n## License\n\nThis project is open source and available under the MIT License.\n\n## Support\n\nFor issues and questions:\n1. Check the troubleshooting section above\n2. Review the test output: `uv run python test_mcp_server.py`\n3. Check Cursor logs for MCP errors\n4. Open an issue on GitHub",
"bugtrack_url": null,
"license": "MIT",
"summary": "A study project: MCP server for direct PDF manipulation and editing",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [
"manipulation",
" mcp",
" pdf",
" server",
" study"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e075e231df02dcdac78ffbd9a94a8b0d7f563cae7c6c0d61a16c3c54b87553a1",
"md5": "731d31b0d821034eca91c7d4bf9d8d4b",
"sha256": "396537528865f077455fa227540f364ea41301066466022beaa0d33f1871af20"
},
"downloads": -1,
"filename": "pdf_manipulation_mcp_server-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "731d31b0d821034eca91c7d4bf9d8d4b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13049,
"upload_time": "2025-10-22T13:28:41",
"upload_time_iso_8601": "2025-10-22T13:28:41.270059Z",
"url": "https://files.pythonhosted.org/packages/e0/75/e231df02dcdac78ffbd9a94a8b0d7f563cae7c6c0d61a16c3c54b87553a1/pdf_manipulation_mcp_server-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "35cb91b47dcf7aabbe79e222b216405e6a71c2ea129ca5de541df9ca508a3399",
"md5": "3daa8b7323ca8fa4e83d2a104870f638",
"sha256": "7c758d85a2968102c231b7d7d30ad2ecb0491633273099f36fb1630d6847fe84"
},
"downloads": -1,
"filename": "pdf_manipulation_mcp_server-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "3daa8b7323ca8fa4e83d2a104870f638",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 60532,
"upload_time": "2025-10-22T13:28:42",
"upload_time_iso_8601": "2025-10-22T13:28:42.458675Z",
"url": "https://files.pythonhosted.org/packages/35/cb/91b47dcf7aabbe79e222b216405e6a71c2ea129ca5de541df9ca508a3399/pdf_manipulation_mcp_server-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 13:28:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pdf-manipulation-mcp-server"
}
JSON