PDF Agent Toolkit & MCP Server (inspired by ihatepdf.cv)
A comprehensive, privacy-first PDF manipulation suite and Model Context Protocol (MCP) server for AI Agents (Claude Desktop, Cursor, Windsurf, LangChain, Claude Code).
Core Philosophy
- Zero Cloud Uploads: All PDF processing (compression, page reordering, rotation, redaction, and text extraction) executes 100% locally in pure TypeScript & WebAssembly.
- Agent Token Optimization: Eliminates context bloat by avoiding raw PDF base64 dumps in prompts; returns structured outlines and page snippets on demand.
- Universal Compatibility: Works out of the box with
stdioJSON-RPC 2.0.
🛠️ Available MCP Tools
| Tool Name | Category | Description | Agent Optimization |
|---|---|---|---|
compress_pdf |
Optimization | Reduces file size via stream defragmentation and DPI presets (screen, ebook, printer). |
Reduces downstream OCR/vision token weight by up to 70%. |
extract_pdf_content |
Intelligence | Extracts document TOC, outline, word count, and clean Markdown text. | Saves ~90% context tokens compared to raw stream dumping. |
scan_and_redact_pii |
Security | Detects SSNs, Emails, Credit Cards, Aadhaar numbers, and custom keywords, stamping black redaction boxes. | Ensures GDPR/HIPAA compliance prior to sending docs to external LLMs. |
organize_pdf |
Structure | Compound tool: reorders, deletes, rotates (90/180/270°), and adds page numbers in one atomic pass. | Prevents multi-turn roundtrips. |
split_pdf |
Structure | Extracts specific page ranges (e.g. "1-3, 5, 8-12"). |
Allows agents to inspect specific chapters. |
merge_pdfs |
Structure | Combines multiple input PDFs into a single document. | Fast multi-file document compilation. |
stamp_watermark |
Security | Stamps visual text watermarks (e.g. "DRAFT", "CONFIDENTIAL") with custom rotation and opacity. |
Visual status stamping. |
create_pdf_from_text |
Creation | Formats clean Markdown/text into an A4 PDF with stylized header banners. | Lightweight document generation without headless browser bloat. |
inspect_and_fill_form |
Forms | Inspects AcroForm fields and fills form data. | Automates invoice, tax, and contract processing. |
🚀 Quickstart Configs for Agents
1. Cursor IDE (.cursor/mcp.json)
{
"mcpServers": {
"pdf-agent-toolkit": {
"command": "npx",
"args": ["-y", "pdf-agent-toolkit-mcp@latest"]
}
}
}
2. Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"pdf-tools": {
"command": "npx",
"args": ["-y", "pdf-agent-toolkit-mcp"]
}
}
}
3. LangChain & LangGraph (Python)
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_google_genai import ChatGoogleGenerativeAI
async def main():
async with MultiServerMCPClient({
"pdf_tools": {
"command": "npx",
"args": ["-y", "pdf-agent-toolkit-mcp"],
"transport": "stdio",
}
}) as client:
tools = client.get_tools()
model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")
agent = create_react_agent(model, tools)
response = await agent.ainvoke({
"messages": [("user", "Compress ./financials.pdf and blackout sensitive SSNs")]
})
print(response)
💻 Running the Server Locally
# Run MCP server on stdio
npm run mcp
# Start the interactive visual testing studio and playground
npm run dev
