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

Conversion Operations

Enhancement Operations

Signature Operations

Utility Operations

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:

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