PDF Redaction MCP Server

A Model Context Protocol (MCP) server for PDF redaction using PyMuPDF (fitz). This server provides tools for loading PDFs, identifying and redacting sensitive text, and saving redacted documents.

Features

• 📄 Load and read PDF files - Extract text content from PDFs for review

• 🔍 Text-based redaction - Search and redact specific text strings across all pages

• 📐 Area-based redaction - Redact specific rectangular regions by coordinates

• 💾 Save redacted PDFs - Apply redactions and save with automatic naming

• 🎨 Customizable redaction appearance - Choose redaction fill colors

• 🔒 Error handling - Comprehensive error messages via MCP protocol

Installation

This project uses uv for package management. To install:

Usage

Running the Server

You can run the server using either the Python script directly or the FastMCP CLI:

Option 1: Direct Python execution (stdio transport)

Option 2: Using FastMCP CLI

Installing in MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Other MCP Clients

Use the FastMCP CLI to generate configuration for other clients:

Available Tools

1. load_pdf

Load a PDF file and extract its text content.

Parameters:

• pdf_path (string): Path to the PDF file to load

Returns: The full text content of the PDF, organized by pages

Example:

2. redact_text

Redact all instances of specific text in a loaded PDF.

Parameters:

• pdf_path (string): Path to the loaded PDF file

• text_to_redact (string): Text string to search for and redact

• fill_color (tuple, optional): RGB color (0-1 range) for redaction box. Default: (0, 0, 0) - black

Returns: Summary of redaction operations

Example:

3. redact_area

Redact a specific rectangular area on a PDF page.

Parameters:

• pdf_path (string): Path to the loaded PDF file

• page_number (int): Page number (1-indexed)

• x0 (float): Left x coordinate

• y0 (float): Top y coordinate

• x1 (float): Right x coordinate

• y1 (float): Bottom y coordinate

• fill_color (tuple, optional): RGB color (0-1 range) for redaction box. Default: (0, 0, 0) - black

Returns: Confirmation message

Example:

4. save_redacted_pdf

Apply all pending redactions and save the PDF.

Parameters:

• pdf_path (string): Path to the loaded PDF file

• output_path (string, optional): Custom output path. If not provided, appends "_redacted" to original filename

Returns: Path to the saved redacted PDF

Example:

5. list_loaded_pdfs

List all currently loaded PDF files.

Parameters: None

Returns: List of loaded PDF paths with page counts

6. close_pdf

Close a loaded PDF and free its resources.

Parameters:

• pdf_path (string): Path to the PDF file to close

Returns: Confirmation message

Workflow Example

Here's a typical workflow using this MCP server:

1. Load a PDF

   Load the PDF at /Users/me/documents/sensitive.pdf

2. Review the content The tool will return the full text content, which you can review to identify sensitive information.

3. Redact sensitive text

   Redact all instances of "Social Security Number" in /Users/me/documents/sensitive.pdf Redact all instances of "123-45-6789" in /Users/me/documents/sensitive.pdf

4. Redact specific areas (optional)

   Redact the area from (50, 100) to (200, 120) on page 2 of /Users/me/documents/sensitive.pdf

5. Save the redacted PDF

   Save the redacted version of /Users/me/documents/sensitive.pdf

   This will create /Users/me/documents/sensitive_redacted.pdf

6. Close the PDF (optional)

   Close /Users/me/documents/sensitive.pdf

Technical Details

Dependencies

• FastMCP (>=2.12.0): Python framework for building MCP servers

• PyMuPDF (>=1.24.0): PDF manipulation library (imported as fitz)

Architecture

• In-memory storage: Loaded PDFs are kept in memory for fast access during redaction operations

• Lazy application: Redaction annotations are added but not applied until save_redacted_pdf is called

• Error handling: Uses FastMCP's ToolError for proper error propagation to MCP clients

• Context logging: All operations log to the MCP context for transparency

Limitations (Current Version)

• Text-only redaction: This version focuses on text redaction. Image redaction is not yet implemented.

• Memory usage: PDFs are kept in memory while loaded. Very large PDFs may consume significant memory.

• Single session: The in-memory store is not persistent across server restarts.

Development

Running Tests

Code Structure

License

[Add your license here]

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

• Built with FastMCP

• PDF manipulation powered by PyMuPDF