gai-mcp-pdf2png

MCP (Model Context Protocol) Server for converting PDF files to PNG images.

Key Feature: Processes pages one at a time, making it memory-efficient for large PDFs.

Installation

npm install -g gai-mcp-pdf2png

Or run directly with npx:

npx gai-mcp-pdf2png

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json):

{
    "mcpServers": {
        "pdf2png": {
            "command": "npx",
            "args": ["gai-mcp-pdf2png"]
        }
    }
}

Available Tools

convert_pdf_to_png

Convert PDF pages to individual PNG images.

Parameters:

• pdfPath (required): Absolute path to the PDF file
• viewportScale (optional): Scale factor for output quality (default: 2.0)
• startPage (optional): First page to convert (1-indexed)
• endPage (optional): Last page to convert

Returns:

• Output directory path (/tmp/{guid})
• List of generated PNG files
• Page count and conversion statistics

Example:

{
    "pdfPath": "/path/to/document.pdf",
    "viewportScale": 2.0,
    "startPage": 1,
    "endPage": 10
}

get_page_count

Get the total number of pages in a PDF without converting it.

Parameters:

• pdfPath (required): Absolute path to the PDF file

Returns:

• Page count

get_image

Retrieve a converted PNG image as base64 data.

Parameters:

• imgPath (required): Absolute path to the image (must be in /tmp)

Returns:

• Base64-encoded image data

ping

Health check endpoint.

Returns:

• "pong"

Why Page-by-Page?

Traditional PDF converters load the entire document into memory before converting. For large PDFs (100+ pages), this can cause:

• Out of memory errors
• Slow processing
• System instability

This MCP server processes one page at a time:

1. Gets total page count (lightweight operation)
2. Converts each page individually
3. Writes to disk immediately
4. Releases memory before next page

Output

PNG files are saved to /tmp/{guid}/ with naming convention:

• page-001.png
• page-002.png
• etc.

Logs

Server logs are written to /tmp/gai-mcp-pdf2png.log for debugging.

License

MIT