pdf-edit-mcp

MCP server for format-preserving PDF text editing. Edit text in existing PDFs while preserving the original fonts, layout, and visual fidelity.

How it works

Most PDF editors use a redact-and-replace approach — they white out the original text and stamp new text on top, usually with a substitute font. The result looks different from the original.

pdf-edit-mcp takes a different approach. It modifies the original PDF content stream operators directly, preserving the exact font, size, color, and position of the text being edited.

Powered by pdf-edit-engine — a Python library for PDF content stream surgery with two-tier font subset extension.

Features

• 38 tools across 7 categories (reading, text editing, block ops, section ops, annotations, document manipulation, metadata & security)
• 3 built-in MCP prompts that guide the editing workflow step by step
• Fidelity reporting — every edit returns whether fonts were preserved, overflow detected, and reflow applied
• Batch operations — up to 500 find-and-replace edits in a single atomic call with auto-verification
• Section intelligence — detects document structure by font hierarchy, swaps sections by fuzzy title match
• Full document manipulation — merge, split, rotate, reorder, crop, watermark, encrypt, decrypt, fill forms
• Runs entirely local — no external APIs, no network calls, no API keys

Quick Start

Prerequisites

• Node.js 20+
• Python 3.12+
• pdf-edit-engine: pip install pdf-edit-engine

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-edit-mcp": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-edit-mcp"]
    }
  }
}

Claude Code

claude mcp add pdf-edit-mcp -- npx -y @aryanbv/pdf-edit-mcp

Other MCP clients (Cursor, Windsurf, etc.)

npx -y @aryanbv/pdf-edit-mcp

Custom Python path

If python isn't in your PATH or you need a specific version:

{
  "mcpServers": {
    "pdf-edit-mcp": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-edit-mcp"],
      "env": {
        "PDF_EDIT_PYTHON": "/path/to/python3.12"
      }
    }
  }
}

Tools

Reading & Analysis

Text Editing

Block Operations

Section Operations

Annotations & Links

Document Manipulation

Metadata & Security

Workflows

Three built-in MCP prompts guide the editing process.

comprehensive-pdf-edit

For structural changes — section swaps, rewrites, multi-field updates:

1. Inspect — Call pdf_inspect to get the full document overview
2. Understand structure — Use pdf_detect_sections for section tree, pdf_find_text for simple text matches, or pdf_get_text_layout for raw block positions
3. Pre-check — Call pdf_analyze_subset if replacement text has unusual characters (bullets, em-dashes, non-Latin scripts)
4. Execute — Use pdf_batch_replace for text changes, pdf_swap_sections or pdf_replace_section for structural changes, then pdf_update_annotation if link URLs changed
5. Verify — Call pdf_get_text on the output. Check for duplicates, missing content, and spurious spaces

section-swap

For swapping two sections by name:

1. Call pdf_detect_sections to get the section tree
2. Identify both sections by title match
3. Call pdf_batch_replace_block with all sibling sections (not just the two being swapped) — unchanged siblings get their original text for uniform spacing
4. Verify with pdf_get_text

quick-pdf-edit

For simple text changes — typos, dates, names:

1. Call pdf_find_text to locate the text
2. Call pdf_replace_text or pdf_replace_single
3. Check font_preserved in the fidelity report

Architecture

AI Agent (Claude, GPT, etc.)
    ↓  MCP protocol (stdio)
index.ts — TypeScript MCP server
    ↓  JSON-RPC 2.0 over stdin/stdout
bridge.py — long-running Python subprocess
    ↓  direct import
pdf-edit-engine — Python library (pikepdf + fonttools + pdfminer)

• The TypeScript server spawns bridge.py once at startup and keeps it alive for all tool calls, avoiding Python startup overhead on every request.
• All inputs are validated by Zod schemas before reaching the Python layer.
• stdout is the IPC channel — all logging goes to stderr.

Tested PDF generators

Limitations

What v0.1.0 does not support:

• Cross-page reflow (text expanding beyond a page boundary)
• Image editing or generation
• Table structure detection
• Encodings beyond Identity-H and WinAnsi
• Right-to-left text

Troubleshooting

"Python not found" — Set PDF_EDIT_PYTHON to your Python 3.12+ path (see Custom Python path).

"No module named pdf_edit_engine" — Install the engine: pip install pdf-edit-engine

Bridge process crashes on startup — Verify Python >=3.12 (python --version) and check stderr for import errors.

Characters not rendering after replacement — Call pdf_analyze_subset before editing to check if the embedded font supports the new characters.

"Path must be absolute" — All pdf_path and output_path values must be absolute paths ending in .pdf.

Development

git clone https://github.com/AryanBV/pdf-edit-mcp.git
cd pdf-edit-mcp
npm install && npm run build

npm test              # validation + security + integration tests
npm run inspect       # launch MCP Inspector for manual testing
npm run audit         # security audit

Integration tests require Python 3.12+, pdf-edit-engine, and reportlab (pip install pdf-edit-engine reportlab).

CI runs in two stages: unit tests (TypeScript validation and security) → integration tests (Python bridge with generated fixtures).

License

MIT