Ilovepdf

An MCP (Model Context Protocol) server that exposes iLovePDF API operations as tools for LLM clients like Claude. Process PDFs directly from your AI conversations - merge, split, compress, convert, and more.

Features

• 22 PDF tools covering all major PDF operations
• Supports both local files and URLs as input
• Customizable output with user-specified directories and filenames
• Operation chaining for complex workflows
• Full TypeScript support with type definitions

Available Tools

Core Operations

Tool	Description
merge-pdfs	Merge multiple PDF files into one
split-pdf	Split PDF by page ranges, fixed intervals, or remove pages
compress-pdf	Reduce PDF file size (low/recommended/extreme)
rotate-pdf	Rotate pages by 90, 180, or 270 degrees
protect-pdf	Add password protection
unlock-pdf	Remove password protection
repair-pdf	Repair damaged PDFs

Conversion Operations

Tool	Description
pdf-to-jpg	Convert PDF pages to JPG images
images-to-pdf	Convert images to PDF
html-to-pdf	Convert webpages to PDF
office-to-pdf	Convert Word, Excel, PowerPoint to PDF
convert-to-pdfa	Convert to PDF/A archive format
validate-pdfa	Validate PDF/A compliance

Enhancement Operations

Tool	Description
add-watermark	Add text or image watermarks
add-page-numbers	Add page numbers with custom formatting
extract-text	Extract text content from PDF
ocr-pdf	OCR scanned PDFs (100+ languages)
edit-pdf	Add text or images to specific positions

Signature Operations

Tool	Description
sign-pdf	Create digital signature requests
get-signature-status	Check signature request status
void-signature	Cancel pending signature requests

Utility Operations

Tool	Description
chain-operations	Chain multiple operations together
list-tasks	List recent API tasks
get-remaining-files	Check API quota

Installation

Prerequisites

• Node.js 18 or higher
• iLovePDF API credentials (get them at developer.ilovepdf.com)

Install from npm

npm install -g ilovepdf-mcp

Install from source

git clone https://github.com/yourusername/ilovepdf-mcp.git
cd ilovepdf-mcp
npm install
npm run build

Configuration

Environment Variables

Create a .env file in your project root:

ILOVEPDF_PUBLIC_KEY=your_public_key_here
ILOVEPDF_SECRET_KEY=your_secret_key_here
DEFAULT_OUTPUT_DIR=./output

Or set environment variables directly in your shell.

Claude Desktop Integration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using .env file (recommended)

If you've set up your .env file with API keys, you only need:

{
  "mcpServers": {
    "ilovepdf": {
      "command": "node",
      "args": ["/path/to/ilovepdf-mcp/dist/index.js"]
    }
  }
}

Option 2: Keys in config only

If you prefer not to use a .env file:

{
  "mcpServers": {
    "ilovepdf": {
      "command": "node",
      "args": ["/path/to/ilovepdf-mcp/dist/index.js"],
      "env": {
        "ILOVEPDF_PUBLIC_KEY": "your_public_key",
        "ILOVEPDF_SECRET_KEY": "your_secret_key",
        "DEFAULT_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

If installed globally via npm:

{
  "mcpServers": {
    "ilovepdf": {
      "command": "ilovepdf-mcp"
    }
  }
}

Usage Examples

Once configured, you can use natural language in Claude to process PDFs:

Merge PDFs

"Merge these three PDF files: report1.pdf, report2.pdf, and appendix.pdf"

Compress PDF

"Compress my large-document.pdf using extreme compression"

Convert to Images

"Convert this PDF to JPG images at 300 DPI"

Add Watermark

"Add a 'CONFIDENTIAL' watermark to all pages of contract.pdf"

Chain Operations

"Compress then merge these PDFs: file1.pdf, file2.pdf, file3.pdf"

OCR

"Make this scanned PDF searchable using English and Spanish OCR"

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Clean build artifacts
npm run clean

API Reference

Common Parameters

Most tools accept these common parameters:

Parameter	Type	Description
file / files	string / string[]	Input file path(s) or URL(s)
outputDir	string?	Output directory (default: ./output)
outputFilename	string?	Custom output filename

Response Format

All tools return a consistent JSON response:

{
  "success": true,
  "message": "Operation completed successfully",
  "outputPath": "/path/to/output.pdf",
  "details": {
    "originalSize": "5.2 MB",
    "outputSize": "1.3 MB"
  }
}

On error:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Troubleshooting

"Missing iLovePDF API credentials"

Ensure ILOVEPDF_PUBLIC_KEY and ILOVEPDF_SECRET_KEY are set in your environment or .env file.

"File not found"

• Check the file path is correct and accessible
• For URLs, ensure they are publicly accessible

"API quota exceeded"

Use get-remaining-files to check your quota. Upgrade your iLovePDF plan if needed.

License

MIT

Credits

• iLovePDF for their excellent PDF API
• Model Context Protocol for the MCP specification
• Built with @modelcontextprotocol/sdk