pdf-manipulation

This MCP server provides a Python-based PDF manipulation toolkit built on PyMuPDF through the MCP FastMCP framework. It exposes a range of capabilities including text and image editing within PDFs, adding and filling annotations and form fields, and extensive page-level operations such as merging, splitting, cropping, rotating, and metadata handling. You can interact with these tools via the MCP interface to programmatically perform common document-editing tasks or to integrate PDF workflows into larger automation pipelines. Typical use cases include converting pages, augmenting PDFs with text or images, extracting embedded images, and adjusting page layouts or metadata.

To use it, start the server via UV (as shown in the Quick Start): uv run pdf-manipulation-mcp-server. Once running, you can invoke the available tools through your MCP client or integration layer. The server exposes functions like pdf_add_text, pdf_replace_text, pdf_add_image, pdf_extract_images, pdf_add_annotation, pdf_add_form_field, pdf_fill_form, pdf_merge_files, pdf_combine_pages_to_single, pdf_split, pdf_rotate_page, pdf_delete_page, pdf_crop_page, pdf_auto_crop_page, pdf_get_info, and pdf_set_metadata. Each tool accepts relevant PDF paths and parameters (e.g., page_number, coordinates, layout options) and returns results or paths to produced PDFs. This makes it suitable for building automated document processing pipelines, QA checks, or batch editing tasks in a reproducible manner.

Prerequisites\n- Python 3.10+ (install from python.org or via your OS package manager)\n- pip (comes with Python)\n\nInstallation options:\n1) Run directly with UV (no installation)\nbash\nuv run pdf-manipulation-mcp-server\n\n2) Install from PyPI\nbash\npip install pdf-manipulation-mcp-server\n# Run the server (entry point defined by the package)\npdf-mcp-server\n\n3) Install from GitHub\nbash\npip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git\n# Run the server\npdf-mcp-server\n\n4) Clone and install locally (development mode)\nbash\ngit clone https://github.com/yourusername/pdf-manipulation-mcp-server.git\ncd pdf-manipulation-mcp-server\npip install -e .\n# Run the server\npdf-mcp-server\n\n5) Development with UV (optional)\nbash\n# Clone and set up in development mode\ngit clone https://github.com/yourusername/pdf-manipulation-mcp-server.git\ncd pdf-manipulation-mcp-server\nuv pip install mcp pymupdf\n# Test the server (optional)\nuv run pytest tests/ -v\n# Run the server\nuv run python server.py\n\n Prerequisites recap: ensure Python 3.10+ is installed and accessible via your PATH, and that you have network access to fetch PyPI packages if you install from PyPI.

Tips and common considerations:\n- The server relies on PyMuPDF (pymupdf); ensure compatible PyMuPDF version is installed for your Python environment.\n- Output files are created with timestamps to avoid overwriting originals. Expect new PDFs to be written to user-specified paths or default output locations referenced by the tool calls.\n- When cropping or cropping with coordinates, confirm coordinate_mode and page_number validity to avoid errors.\n- For Cursor IDE/Cursor configuration, you can point to the UV command as shown in the sample MCP config; this makes it easy to integrate with Cursor workflows.\n- If you encounter environment path issues, ensure your shell can resolve uv (or uvx) and that the working directory is correctly set when configuring in editors or IDEs.\n- The server exposes a broad set of operations; when composing pipelines, consider chaining operations (e.g., extract_images then process them, or add_text followed by crop) to minimize I/O.\n- For debugging, enable verbose logging in your MCP client to capture tool parameters and error messages returned by the server.