pdf-render-mcp

An MCP (Model Context Protocol) server that renders PDF pages as JPEG/PNG images using PyMuPDF. Designed for AI assistants like Claude and Cursor to visually inspect PDF content including charts, formulas, layouts, and more.

Features

• Smart width-based scaling — consistent output size regardless of PDF page dimensions
• JPEG by default — significantly smaller payload than PNG for faster AI processing
• DPI override — precise control when needed for high-quality output
• Optimized defaults — 1600px width + JPEG q80 balances quality, speed, and size

Prerequisites

• Node.js >= 18
• Python >= 3.8 with PyMuPDF installed:

pip install pymupdf

Installation & Usage

Use with Cursor

Add to your MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "pdf-renderer": {
      "command": "npx",
      "args": ["-y", "pdf-render-mcp"]
    }
  }
}

Use with Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "pdf-renderer": {
      "command": "npx",
      "args": ["-y", "pdf-render-mcp"]
    }
  }
}

Tool: pdf_to_images

Renders PDF pages as base64-encoded images (JPEG or PNG).

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | path | string | Yes | — | Absolute or relative path to the PDF file | | pages | number[] | No | all | Page numbers to render (1-based). Max 20 per request | | max_width | integer | No | 1600 | Target image width in pixels (600–4000). Lower = faster & smaller | | dpi | integer | No | — | Explicit DPI override (72–400). When set, overrides max_width | | format | string | No | jpeg | Image format: jpeg (smaller, faster) or png (lossless) | | quality | integer | No | 80 | JPEG quality 30–100. Only applies when format is jpeg |

Examples

Default (fast, good quality for AI):

{
  "path": "/path/to/document.pdf",
  "pages": [1, 2, 3]
}

High quality:

{
  "path": "/path/to/document.pdf",
  "max_width": 2400,
  "quality": 90
}

Compact (faster, smaller):

{
  "path": "/path/to/document.pdf",
  "max_width": 1200,
  "quality": 70
}

Explicit DPI:

{
  "path": "/path/to/document.pdf",
  "dpi": 300,
  "format": "png"
}

Configuration

| Environment Variable | Description | |---------------------|-------------| | PDF_RENDER_PYTHON | Path to a specific Python executable (e.g. /usr/bin/python3) |

Limits

• Max file size: 50 MB
• Max pages per request: 20
• Max concurrent renders: 4
• Worker timeout: 120 seconds

License

MIT