PDF Toolkit MCP

pdf-toolkit-mcp

18 PDF operations for Claude Code, Claude Desktop, and any MCP client — via iLoveAPI.

Install · Tools · Recipes · Architecture · Security · FAQ

---

Disclaimer. pdf-toolkit-mcp is an independent, community-built open-source client. It is not affiliated with, endorsed, sponsored, or certified by iLovePDF SL. The project talks to the public iLoveAPI REST service using *your* project credentials — nothing is proxied, resold, or relicensed. "iLovePDF" and "iLoveAPI" are trademarks of iLovePDF SL; this project does not claim ownership of those marks.

---

📖 Table of contents

• Why pdf-toolkit-mcp
• Quick tour
• Install
• Tool catalog
• Workflow recipes
• Architecture
• Configuration reference
• Security model
• Development
• Testing & CI
• Releasing
• Roadmap
• FAQ
• Contributing
• License & trademarks
• Credits

---

🎯 Why pdf-toolkit-mcp

Free for personal use. iLoveAPI's free tier grants ~2,500 credits / month; this MCP itself is MIT-licensed and costs nothing.

---

🚀 Quick tour

After installation, just *talk* to Claude. The model figures out which tools to call:

You: Merge invoice-jan.pdf and invoice-feb.pdf into Q1.pdf, then compress it hard

and lock it with the password "2026q1".

Claude (planning):

1. merge_pdf → invoice-jan.pdf + invoice-feb.pdf → Q1.pdf
2. compress_pdf → Q1.pdf → Q1-compressed.pdf (level: extreme)
3. protect_pdf → Q1-compressed.pdf → Q1-compressed-protected.pdf

Claude (result): ✅ Created ~/docs/Q1-compressed-protected.pdf (312 KB, password-protected).

---

📦 Install

Prerequisites

• Node.js ≥ 18 (LTS recommended).
• iLoveAPI project keys — free tier at developer.ilovepdf.com. Takes ~2 minutes:

1. Sign up → create a project → copy Project public key and Project secret key.
2. Export them (or drop them into your client's MCP config — examples below).

Option A — Claude Code (CLI one-liner)

export ILOVEAPI_PROJECT_PUBLIC_KEY="project_public_xxx"

export ILOVEAPI_PROJECT_SECRET_KEY="secret_key_xxx"

claude mcp add pdf-toolkit -- npx -y pdf-toolkit-mcp

Restart Claude Code and all 18 tools appear in the picker. Verify with /mcp → you should see pdf-toolkit: connected (18 tools).

Option B — Claude Code Plugin (includes the pdf-workflow skill)

/plugin marketplace add EigenCharlie/pdf-toolkit-mcp

/plugin install pdf-toolkit@EigenCharlie/pdf-toolkit-mcp

The plugin auto-configures the MCP server *and* installs a skill that teaches Claude five canonical multi-step PDF pipelines (see Workflow recipes).

Option C — Claude Desktop (claude_desktop_config.json)

Click to expand

Edit claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{

"mcpServers": { "pdf-toolkit": { "command": "npx", "args": ["-y", "pdf-toolkit-mcp"], "env": { "ILOVEAPI_PROJECT_PUBLIC_KEY": "project_public_xxx", "ILOVEAPI_PROJECT_SECRET_KEY": "secret_key_xxx" } } } }

Restart Claude Desktop — the 🔌 icon should show pdf-toolkit connected.

Option D — any MCP client via stdio

ILOVEAPI_PROJECT_PUBLIC_KEY=… ILOVEAPI_PROJECT_SECRET_KEY=… npx -y pdf-toolkit-mcp

The server speaks the standard MCP JSON-RPC 2.0 framing over stdio. Wire it into Cursor, Windsurf, mcphub, mcp-inspector, or anything else that speaks MCP.

Option E — Claude Desktop .mcpb bundle (drag-and-drop)

Grab pdf-toolkit-mcp- .mcpb from the latest GitHub Release and drag it into Claude Desktop → Settings → Extensions. Claude will prompt for your iLoveAPI keys via the user_config section of the bundled manifest. No npx, no Node, no terminal.

Bundles ship unsigned (no publisher certificate yet). macOS Gatekeeper / Windows SmartScreen may warn on first install; verify the SHA-256 in the release notes before accepting.

Option F — MCP Registry (auto-discovered by compatible clients)

The server is indexed on the official MCP Registry under io.github.EigenCharlie/pdf-toolkit-mcp. Clients that browse the registry (Claude Desktop extension pane, VS Code MCP picker, mcphub, etc.) can install it without any manual config — they'll point at the npm package and prompt for the two iLoveAPI env vars automatically.

---

🧰 Tool catalog

All 18 tools are exposed with strict Zod schemas, additionalProperties: false, and return both a text summary *and* a file:// resource URI so the client can surface the output.

📚 Organize

🔄 Convert — from PDF

🔄 Convert — to PDF

✏️ Edit

🔐 Security

🩹 Repair / OCR

All tools accept absolute or CWD-relative paths for input_file(s) and an optional output_path (file or directory). Defaults place the result next to the first input with a timestamped name.

---

🍳 Workflow recipes

The bundled pdf-workflow skill (skills/pdf-workflow/SKILL.md) teaches Claude five canonical multi-step pipelines. You can also run these manually — just describe the end state and Claude chains the tools for you.

1. Assemble — merge + compress + (optional) protect

merge_pdf([a.pdf, b.pdf, c.pdf])

→ compress_pdf(level="recommended") → protect_pdf(password="…")

</details>

1. Convert & secure — Office doc to locked PDF

office_to_pdf(report.docx)

→ add_watermark(mode="text", text="CONFIDENTIAL", opacity=30) → protect_pdf(password="…")

</details>

1. Extract & OCR — pull pages out of a scan and make them editable

extract_pdf_pages(scan.pdf, pages="3-9")

→ ocr_pdf(languages=["eng"]) → pdf_to_word

</details>

1. Prep for email — shrink + lock

compress_pdf(big.pdf, level="extreme")

→ protect_pdf(password="…")

</details>

1. Scan cleanup — repair + OCR + number

repair_pdf(scan_broken.pdf)

→ ocr_pdf(languages=["eng"]) → add_page_numbers(position="bottom-center")

</details>

---

🏛 Architecture

┌────────────────────────────┐    stdio    ┌──────────────────────────┐

│ Claude Code / Desktop │◀───────────▶│ pdf-toolkit-mcp server │ │ (or any MCP client) │ JSON-RPC │ (this repo) │ └────────────────────────────┘ └────────────┬─────────────┘ │ ▼ ┌──────────────────────┐ │ @ilovepdf/ │ │ ilovepdf-nodejs │ │ (JWT + HTTP) │ └──────────┬───────────┘ │ ▼ HTTPS ┌──────────────────────┐ │ iLoveAPI servers │ │ api.ilovepdf.com │ └──────────────────────┘

iLoveAPI 5-phase lifecycle (orchestrated in src/api/tasks.ts)

  [ 10% ]   start     →  POST /v1/start/{tool}     (server assignment + task id)

[ 40% ] upload → POST /v1/upload (one call per file, progress scales) [ 50% ] proce