pdf-modifier-mcp
# PDF Modifier MCP
**CLI + MCP server + Web UI** for PDF text replacement with font style preservation.
[](https://github.com/mlorentedev/pdf-modifier-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/pdf-modifier-mcp/)
[](https://www.python.org/downloads/)
[](https://mlorentedev.github.io/pdf-modifier-mcp/)
[](https://opensource.org/licenses/MIT)
## Quick start
```bash
pip install pdf-modifier-mcp
# CLI
pdf-mod modify input.pdf output.pdf -r "Draft=Final"
# MCP server (for Claude/Cursor/Codex)
claude mcp add -s user pdf-modifier -- uvx pdf-modifier-mcp
```
## Interfaces
| Interface | Description | Run |
|-----------|-------------|-----|
| **CLI** | `pdf-mod` — batch jobs, scripting, CI pipelines | `make run cli ARGS="..."` |
| **MCP Server** | `pdf-modifier-mcp` — AI agents edit PDFs | `make run mcp` |
| **Web UI** | FastAPI + SvelteKit — drag & drop, preview, replace | `make up` (Docker) or `make run api` + `make run frontend` |
## Features
- **Text replacement** — find and replace with font style preservation (family, weight, size, color)
- **Regex support** — pattern-based bulk replacements (`--regex`)
- **Hyperlinks** — create clickable links or neutralize existing ones
- **Batch processing** — apply same replacements to multiple files
- **Web UI** — drag & drop PDF upload, structure browser, page preview with zoom, text highlighting
- **MCP tools** — `read_pdf_structure`, `inspect_pdf_fonts`, `list_pdf_hyperlinks`, `modify_pdf_content`
## Development
```bash
# Setup
make setup
# Run tests
make test
# Full check (lint + type + test)
make check
# Start dev stack (Docker)
make up
# API: http://localhost:8000 | Web: http://localhost:8080
# Start servers locally
make run api # FastAPI dev server
make run frontend # SvelteKit dev server
```
## Documentation
- [Full documentation site](https://mlorentedev.github.io/pdf-modifier-mcp/)
- [Architecture Decision Records](docs/adr/)
- [Troubleshooting](docs/troubleshooting/)
- [Lessons learned](docs/lessons.md)
## License
MIT
TDQS
Scored across 6 tools
Most tools have clearly distinct purposes: reading structure, modifying content, listing hyperlinks, and batch processing are unambiguous. However, read_pdf_structure and inspect_pdf_fonts both report font name, size, and coordinates, so an agent could be uncertain which to use when investigating text styling.
All tools follow a consistent verb_noun snake_case pattern (extract_, read_, inspect_, modify_, list_, batch_modify_). The batch_ prefix clearly signals the multi-file variant of modify_pdf_content, making the naming predictable and scannable.
Six tools is a well-scoped set for a PDF modification server. Each tool covers a distinct aspect of the domain—inspection, single-file modification, batch modification, font analysis, and hyperlink inventory—without bloat or redundancy.
The core workflow is covered: read structure, inspect fonts, modify text, list hyperlinks, and batch process. Minor gaps exist such as no page-level operations (reorder, delete, rotate) or image extraction, but these fall outside the server's evident text-and-link modification focus.