ilovepdf-mcp

iLovePDF MCP Server

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