PaperPilot MCP
# PaperPilot
**PDF tools for your AI agent — and for you. Pure Rust. Runs locally. Files never leave your machine.**
[](https://github.com/KrushnaVardhanReddy/PaperPilot/actions)
[](https://github.com/rust-unofficial/awesome-rust#utilities)
[](https://www.npmjs.com/package/@usepaperpilot/mcp)
[](https://glama.ai/mcp/servers/KrushnaVardhanReddy/PaperPilot)
[](SECURITY.md)
[](SECURITY.md)
[](LICENSE)
[](https://www.rust-lang.org)
[](https://modelcontextprotocol.io)
[](CONTRIBUTING.md)

[**Try it in your browser →**](https://usepaperpilot.com) · [Download](https://github.com/KrushnaVardhanReddy/PaperPilot/releases) · [Contributing](CONTRIBUTING.md) · [Roadmap](ROADMAP.md)
PaperPilot is a PDF and document toolkit written in Rust. The same engine runs as:
| Surface | Use it for |
|---|---|
| **MCP server** | Give Codex, Claude Code, Gemini CLI, Cursor, Claude Desktop, or any MCP client instant document superpowers |
| **CLI** | High-speed batch workflows and automated terminal pipelines |
| **Browser Extension** | In-tab right-click actions on web/arXiv PDFs, clean article capture, and WASM toolkit |
| **Browser (WASM)** | Zero-install web tools; files are processed in browser memory, nothing is uploaded |
| **Desktop app** | Tauri + Svelte 5 GUI with interactive canvas, viewer, and pipeline builder |
| **Local REST API** | Call it from Python, Node.js, n8n, LangChain, or LlamaIndex at `localhost:7823` |
No Chromium, no C++ runtime, no cloud calls.
---
## Self-Healing System Diagnostics
Verify your environment, gateway port, temp storage, and OCR models with one command:
```bash
paperpilot doctor
# PaperPilot System Diagnostics (v0.7.0)
# ==================================================
# Status: Healthy
# [✓] Temp Directory: /tmp (writable & ephemeral cleanup verified)
# [✓] Gateway Port: 7823 available
# [✓] OCR Models: models/ocr/ppocrv4 (det.onnx, rec.onnx found)
# [✓] Disk Space: > 5 GB available
```
**Open-WebUI integration (source builds):** use the local gateway as a
PDF-only Tika-compatible extraction server. See the
[Open-WebUI setup guide](docs/integrations/open_webui.md).
---
## Quick start
### 1. Use it with your AI / Coding Agent (5-Second MCP Setup)
No manual build or binary download required! Run instantly via `npx`:
```bash
# Test MCP server directly
npx -y @usepaperpilot/mcp --help
```
Add to **Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`cursor_mcp_config.json`), **Windsurf**, or **Zed**:
```json
{
"mcpServers": {
"paperpilot": {
"command": "npx",
"args": ["-y", "@usepaperpilot/mcp"]
}
}
}
```
Or if using the precompiled native binary, download `paperpilot-mcp` from [Releases](https://github.com/KrushnaVardhanReddy/PaperPilot/releases) or use client config generators:
```bash
paperpilot-mcp --client-config cursor
# Also: claude-desktop, claude-code, codex, kimi-code, pi
```
Restart Claude and try: *"Merge these two PDFs and compress the result."*
### 2. Use the CLI
```bash
# Semantic Chunking for AI Agents & RAG (Spec 159)
paperpilot pdf-chunk --input contract.pdf --target-tokens 500 --overlap 50 --json
# Merge multiple documents
paperpilot merge --inputs doc1.pdf doc2.pdf --output merged.pdf
# High-efficiency compression
paperpilot compress --input in.pdf --quality 75 --output compressed.pdf
# Search pattern or keywords across document pages
paperpilot search --input in.pdf --query "Invoice" --json
# Rotate pages 1, 3–5 by 90°
paperpilot rotate --input in.pdf --pages 1,3-5 --angle 90 --output out.pdf
```
### 3. Use it in the browser & extension
- **Web App**: Go to [usepaperpilot.com](https://usepaperpilot.com) for zero-install client-side WebAssembly tools.
- **Companion Extension**: Load the Manifest V3 browser extension from [`apps/extension`](apps/extension) for in-tab context menus, right-click PDF actions, and clean web article capture.
### 4. Build from source
```bash
git clone https://github.com/KrushnaVardhanReddy/PaperPilot.git
cd PaperPilot
cargo build --release -p paperpilot-cli -p paperpilot-mcp -p paperpilot-gateway
```
Desktop app:
```bash
cd apps/desktop && pnpm install && pnpm tauri dev
```
Requires Rust 1.75+, Node.js, and pnpm.
---
## What it can do (92 Tools Across 5 Interfaces)
- **AI Agent Intelligence, Semantic Search & Workflows**:
- `document_workflow` & `recipe_run`: Declarative `.ppflow` DAG workflows with step dependencies, conditions, and cryptographic audit receipts.
- `workspace_search` & `semantic_search`: Multi-format recursive workspace search (`.pdf`, `.docx`, `.xlsx`, `.md`, `.txt`, `.csv`, `.json`) and normalized vector chunk retrieval.
- `cli_ask`: Natural language intent planner and instant execution agent.
- `pdf_chunk` & `pdf_rag_chunks`: Structure-aware semantic chunker respecting `#`/`##` headings, `\n\n` paragraphs, and keeping Markdown tables atomic.
- `pdf_search` & `pdf_extract_patterns`: High-precision regex and pattern extraction for invoices, order IDs, and legal identifiers.
- `pdf_classify_type`: Automatic document categorization (invoices, receipts, legal briefs, tax filings, research papers).
- **Core Layout, Bates Numbering & Imposition**:
- `pdf_bates`: Standard legal discovery Bates numbering across 6 customizable anchor positions.
- Merge, split, rotate, delete pages, reorder pages, extract pages, booklet imposition, N-up grid, and multi-sheet poster tile slicing (`pdf_posterize`).
- Interactive forms: read form fields (`pdf_read_form`), fill (`pdf_fill_form`, `batch_fill`), create form fields (`pdf_create_form_field`), and flatten (`pdf_flatten`).
- Digital signatures & timestamps (`pdf_sign`, `pdf_validate_signatures`, `pdf_timestamp`), bookmarks (`pdf_bookmarks`), and crop/scale (`pdf_crop`, `pdf_scale_pages`).
- **Office & Cross-Format Transformations**:
- Bidirectional PDF ⇄ Word (`pdf_to_docx`, `pdf_convert_markdown`).
- Bidirectional PDF ⇄ Excel (`pdf_to_xlsx`, `pdf_convert_excel`, `excel_to_csv`, `excel_to_json`).
- EPUB eBooks (`pdf_to_epub`), PowerPoint slides (`pdf_to_pptx`), HTML (`pdf_to_html`, `pdf_convert_html`), and JSON ASTs (`pdf_to_json`, `json_to_pdf`).
- Legacy Office modernization (`office_modernize_legacy`, `office_extract_text`, `office_to_markdown`).
- **OCR & Document Vision**:
- Neural PP-OCRv4 detection & recognition via `rten` and `ocrs` (det.onnx + rec.onnx).
- Searchable OCR text layer injection, auto-rotation (`pdf_auto_rotate`), page rendering (`pdf_render`), and blank page removal (`pdf_remove_blank`).
- **Security & PII Redaction**:
- Automated PII scanning (`document_pii_scan`) detecting SSNs, credit cards, emails, phone numbers, and IBANs.
- Permanent redaction (`pdf_redact`) via coordinates, keywords, regex, or structured JSON datasets.
- Cryptographic validation & hashing (`pdf_validate`, `pdf_hash`), encryption/decryption (`pdf_encrypt`, `pdf_decrypt`), permissions bitmask (`pdf_change_permissions`), and sanitization (`pdf_sanitize`).
- **Zero-Copy High Performance Engine**:
- Zero-copy memory-mapped I/O (`DocumentSource` via `memmap2`) for files $\ge 10\text{ MB}$, keeping resident memory flat (< 100 MB) during search, chunking, and PII scanning of 500+ page documents.
- Universal streaming page batching (`PageBatchIterator`) to prevent OOM errors.
---
## Why another PDF tool?
- **Private by default.** Everything runs locally or in your browser tab.
- **Agent-ready.** MCP support is first-class, not an afterthought.
- **One engine, many surfaces.** CLI, MCP, REST, WASM, and desktop share the same Rust core, so behavior is consistent.
- **Small and dependency-light.** Pure Rust, built on [`lopdf`](https://github.com/J-F-Liu/lopdf), [`pdf_oxide`](https://crates.io/crates/pdf_oxide), [`rten`](https://github.com/robertknight/rten), and friends.
## Benchmarks
<!-- TODO: add a real table: operation | input size | time | machine -->
Run `cargo bench --workspace` to reproduce. Methodology and results: [SYSTEM_BENCHMARK_REPORT.md](SYSTEM_BENCHMARK_REPORT.md).
---
## Architecture
```
Desktop (Tauri) · CLI · REST (Axum) · MCP (stdio) · WASM (browser / edge)
│
Rust core workspace
paperpilot-core · paperpilot-pdf · paperpilot-nlp · paperpilot-gateway
paperpilot-mcp · paperpilot-wasm · paperpilot-storage
```
## Embed in your own site
```html
<script src="https://usepaperpilot.com/embed.js" data-tools="merge,compress,ocr"></script>
<div id="paperpilot-widget"></div>
```
## Local REST API & Document Ingestion
```bash
paperpilot serve --port 7823
# Standard PDF Operations (JSON & multipart)
curl -X POST http://localhost:7823/api/v1/pdf/merge \
-H "Content-Type: application/json" \
-d '{"inputs": ["a.pdf", "b.pdf"], "output": "out.pdf"}'
# Open-WebUI & Tika In-Memory Ingestion (sub-5ms)
curl -X PUT http://localhost:7823/tika/text \
-H "Content-Type: application/pdf" \
--data-binary @sample.pdf
```
Interactive Swagger OpenAPI docs at `http://localhost:7823/swagger-ui`.
## Security & Supply Chain Integrity
PaperPilot processes sensitive, proprietary, and personal documents on-device without cloud dependencies. We maintain rigorous software supply chain and security compliance:
- **OpenSSF Scorecard**: **8.2 / 10**
- **Token Permissions**: 100% scoped to `permissions: read-all` (principle of least privilege).
- **SAST & Secret Gate**: Continuous Semgrep OSS and Trivy security audits gating all commits.
- **Dependency Hardening**: All third-party GitHub Actions pinned to immutable 40-character commit SHAs.
- **Responsible Disclosure**: See [`SECURITY.md`](SECURITY.md) for our vulnerability disclosure policy and 48-hour response SLA.
---
## Contributing & Community
Issues and PRs are welcome. Good first contributions: bug reports with a sample PDF, new tool requests, and docs fixes.
Special thanks to all community members and contributors recognized in [CONTRIBUTORS.md](CONTRIBUTORS.md).
## License
Community Edition (this repo): [Apache 2.0](LICENSE). It includes the CLI, MCP server, REST gateway, WASM engine, and desktop app.
An Enterprise Edition (SSO, RBAC, audit logs, DLP) is developed separately.
This server cannot be deployed
TDQS
Scored across 95 tools
Several tools are near-exact aliases or overlapping: pdf_convert_html/html_to_pdf, pdf_convert_markdown/md_to_pdf, pdf_images_to_pdf/img_to_pdf, and batch_fill/cli_fill_batch. Extraction and search also blur together across pdf_extract_text, pdf_to_markdown, pdf_to_json, pdf_chunk, pdf_rag_chunks, semantic_search, workspace_search, and pdf_search, making misselection likely.
Most names use snake_case and a pdf_ prefix, but the set mixes pdf_, office_, excel_, cli_, watcher_, execution_receipt_, and bare names like semantic_search. The action naming is also uneven, with noun-style names such as pdf_info and pdf_metadata alongside verb-style tools, and duplicate aliases break the pattern.
95 tools is far beyond a well-scoped surface, even for a broad PDF/document toolkit. The count is inflated by duplicate aliases and many niche operations, though the domain is large enough that the overall breadth is not entirely unjustified.
Coverage is very extensive across conversion, editing, forms, OCR, redaction, security, signatures, workflow automation, watchers, and receipts. There are minor gaps such as real digital signing being a stub and no explicit page-insertion tool, but most document lifecycle operations are covered.