pdf-toolkit-mcp
18 PDF operations for Claude Code, Claude Desktop, and any MCP client — via iLoveAPI.
Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
ILOVEAPI_PROJECT_PUBLIC_KEY=<secret> ILOVEAPI_PROJECT_SECRET_KEY=<secret> ILOVEAPI_SANDBOX_ROOT=<value> claude mcp add io.github.eigencharlie-pdf-toolkit-mcp -- npx -y pdf-toolkit-mcp@0.1.2In einem Terminal ausführen.
{ "mcpServers": { "io.github.eigencharlie-pdf-toolkit-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "ILOVEAPI_PROJECT_PUBLIC_KEY": "<secret>", "ILOVEAPI_PROJECT_SECRET_KEY": "<secret>", "ILOVEAPI_SANDBOX_ROOT": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenDisclaimer.
pdf-toolkit-mcpis 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.
Free for personal use. iLoveAPI's free tier grants ~2,500 credits / month; this MCP itself is MIT-licensed and costs nothing.
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).
Project public key and Project secret key.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).
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).
claude_desktop_config.json)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.
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.
.mcpb bundle (drag-and-drop)Grab pdf-toolkit-mcp-<version>.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.
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.
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.
All tools accept absolute or CWD-relative paths for
input_file(s)and an optionaloutput_path(file or directory). Defaults place the result next to the first input with a timestamped name.
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.
merge_pdf([a.pdf, b.pdf, c.pdf])
→ compress_pdf(level="recommended")
→ protect_pdf(password="…")
office_to_pdf(report.docx)
→ add_watermark(mode="text", text="CONFIDENTIAL", opacity=30)
→ protect_pdf(password="…")
extract_pdf_pages(scan.pdf, pages="3-9")
→ ocr_pdf(languages=["eng"])
→ pdf_to_word
compress_pdf(big.pdf, level="extreme")
→ protect_pdf(password="…")
repair_pdf(scan_broken.pdf)
→ ocr_pdf(languages=["eng"])
→ add_page_numbers(position="bottom-center")
┌────────────────────────────┐ 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 │
└──────────────────────┘
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% ] process → POST /v1/process (run the tool with params)
[ 90% ] download → GET /v1/download/{task} (bytes → Buffer)
[100% ] done → write to disk, emit file:// resource URI
The server emits MCP notifications/progress at each boundary so your client can render a live progress bar for slow operations (OCR, large merges).
pdf-toolkit-mcp/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest
│ └── .mcp.json # MCP server config (npx -y pdf-toolkit-mcp)
├── skills/
│ └── pdf-workflow/
│ └── SKILL.md # 5-recipe skill for multi-step pipelines
├── src/
│ ├── index.ts # #!/usr/bin/env node shebang
│ ├── server.ts # MCP stdio bootstrap
│ ├── api/
│ │ ├── client.ts # iLoveAPI client singleton (CJS interop via createRequire)
│ │ ├── tasks.ts # 5-phase lifecycle orchestrator
│ │ ├── errors.ts # HTTP → structured PdfToolkitError mapping
│ │ └── types.ts # Types + error class
│ ├── tools/ # 18 tools, one file per concern
│ │ ├── _shared.ts # Zod fragments + writeOutputAndReport helper
│ │ ├── merge.ts split.ts compress.ts
│ │ ├── convertFromPdf.ts convertToPdf.ts
│ │ ├── pageOps.ts security.ts watermark.ts
│ │ ├── repair.ts ocr.ts
│ │ └── index.ts # allTools[] barrel
│ └── util/
│ ├── paths.ts # resolveInputs/resolveOutput + sandbox enforcement
│ ├── progress.ts # Progress adapter
│ └── logger.ts # stderr-only logger (stdio-safe)
├── tests/
│ ├── unit/ # client, paths, errors, tools.merge (25 tests)
│ └── integration/ # smoke.test.ts — gated on iLoveAPI creds
├── scripts/
│ └── inspector.sh # npm run inspect → MCP Inspector UI
└── .github/workflows/
├── ci.yml # ubuntu+windows × node 18/20/22
└── publish.yml # Publishes to npm on v* tags with --provenance
Every failure surfaces a PdfToolkitError with a stable machine-readable code:
pdf-toolkit-mcp is designed to be safe to install on a developer machine:
api.ilovepdf.com via the official SDK.console.log. JSON-RPC over stdio would corrupt on any stray stdout write, so every log line goes through process.stderr.@ilovepdf/ilovepdf-nodejs SDK self-signs JWTs with your secret key — no secret leaves the machine.ILOVEAPI_SANDBOX_ROOT to constrain the server to a single directory tree; any path resolving outside throws before the API is ever called.html_to_pdf rejects .exe; image_to_pdf only accepts common raster formats, etc.git clone https://github.com/EigenCharlie/pdf-toolkit-mcp.git
cd pdf-toolkit-mcp
npm install
npm run build.claude mcp remove pdf-toolkit # if previously registered
claude mcp add pdf-toolkit -- node "$(pwd)/dist/index.js"
PDF_TOOLKIT_DEBUG=1 in your shell before launching Claude Code for verbose stderr.claude mcp logs pdf-toolkit.client, paths, errors, and tools.merge. Fully mocked, no network. Run with npm test.tests/integration/smoke.test.ts spins up two minimal valid PDFs and exercises a real merge_pdf end-to-end. Gated on ILOVEAPI_*_KEY env vars; automatically skipped in PR CI for security.lint → typecheck → build → test on:
ubuntu-latest, windows-latest18, 20, 22Publishing is automated on tag push:
npm version patch # or minor / major
git push --follow-tags
The publish workflow then:
--access public --provenance (supply-chain attestation).Repo secret required: NPM_TOKEN (npm automation token).
.mcpb) for Claude Desktop, marketplace manifest, MCP Registry submission (mcpName)anthropics/claude-plugins-official, publish an image-tools companion packHave a feature request? Open an issue.
Is this legal / safe / allowed by iLovePDF? Yes. It's a thin open-source client that uses your credentials — nothing is resold, relicensed, or proxied. The iLoveAPI Terms of Service explicitly permit open-source libraries using user-provided keys (several community SDKs have existed for years). This project does not ship any keys, does not use "iLovePDF"/"iLoveAPI" in its package name, and carries the required disclaimer.
Does it cost money? iLoveAPI offers ~2,500 credits per month free (enough for thousands of small ops). Heavier workloads need a paid iLoveAPI plan. This MCP itself is MIT and free forever.
Does it work offline? No. iLoveAPI is cloud-only, so every tool call requires internet access.
Can I pin a specific version?
Yes: claude mcp add pdf-toolkit -- npx -y [email protected].
Can I self-host?
Yes. Clone the repo, npm run build, and point your client at node ./dist/index.js. The server is entirely stateless.
What happens if iLoveAPI is down?
The tool returns a PdfToolkitError with code: "API_ERROR" and data.http_status. Claude can retry with exponential backoff on your behalf.
Can I use this without Claude? Yes — any MCP-compatible client works: Cursor, Windsurf, Zed, MCP Inspector, custom clients. The server is 100% spec-compliant.
Contributions welcome! Small checklist before opening a PR:
npm run lint && npm run typecheck && npm test → all green.runTask → writeOutputAndReport).Bug reports are even more welcome — include the tool name, the arguments, and (if safe to share) the stderr output.
Released under the MIT License © 2026 Carlos.
"iLovePDF" and "iLoveAPI" are trademarks of iLovePDF SL. This project is an independent, community-built client and is not affiliated with, endorsed by, sponsored by, or certified by iLovePDF SL. The package name intentionally avoids both marks.
@modelcontextprotocol/sdk, Zod, Vitest, ESLint — the toolchain this project stands on.Unofficial PDF toolkit (merge/split/compress/OCR/convert/watermark/protect/...) via iLoveAPI.
{ "mcpServers": { "io.github.eigencharlie-pdf-toolkit-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "ILOVEAPI_PROJECT_PUBLIC_KEY": "<secret>", "ILOVEAPI_PROJECT_SECRET_KEY": "<secret>", "ILOVEAPI_SANDBOX_ROOT": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: ILOVEAPI_PROJECT_PUBLIC_KEY, ILOVEAPI_PROJECT_SECRET_KEY, ILOVEAPI_SANDBOX_ROOT.
Pdf Toolkit läuft lokal über stdio.
Zuletzt geprüft: 2026-11-09. Unofficial PDF toolkit (merge/split/compress/OCR/convert/watermark/protect/...) via iLoveAPI.