HTML to PDF MCP Server

MCP (Model Context Protocol) server for converting HTML files or HTML content to PDF using Puppeteer's browser rendering engine.

Features

Convert HTML files to PDF with high-fidelity browser rendering
Convert HTML content strings to PDF
Full CSS and JavaScript support
Configurable page format, margins, orientation
Header and footer templates
Background graphics printing
Wait for network idle option
Browser instance pooling for performance

Installation

npm install
npm run build

Usage

Quick Start with Claude Code/Desktop

This server is designed to work with Claude Code and Claude Desktop as an MCP tool.

📖 For detailed MCP setup and usage instructions, see MCP_USAGE.md

Basic MCP Configuration

Add to your MCP client configuration:

Claude Code: ~/.config/claude-code/mcp_config.json Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "html2pdf": {
      "command": "node",
      "args": ["/absolute/path/to/html2pdf/dist/index.js"],
      "description": "Convert HTML to PDF with browser rendering"
    }
  }
}

After configuration, restart Claude and ask:

Claude, convert my-report.html to PDF with 80% scale and A4 format

Available Tool

`convert_html_to_pdf`

Convert HTML to PDF with browser rendering.

Parameters:

htmlPath (string, optional): Path to HTML file to convert
htmlContent (string, optional): HTML content string to convert (alternative to htmlPath)
outputPath (string, optional): Output PDF file path (default: auto-generated with timestamp)
format (string, optional): Paper format - A4, A3, Letter, Legal, Tabloid (default: A4)
landscape (boolean, optional): Use landscape orientation (default: false)
printBackground (boolean, optional): Print background graphics (default: true)
scale (number, optional): Scale of webpage rendering, 0.1-2 (default: 1)
marginTop (string, optional): Top margin (default: 10mm)
marginBottom (string, optional): Bottom margin (default: 10mm)
marginLeft (string, optional): Left margin (default: 10mm)
marginRight (string, optional): Right margin (default: 10mm)
displayHeaderFooter (boolean, optional): Display header and footer (default: false)
headerTemplate (string, optional): HTML template for header
footerTemplate (string, optional): HTML template for footer
waitForNetworkIdle (boolean, optional): Wait for network to be idle (default: false)
timeout (number, optional): Maximum time to wait in milliseconds (default: 30000)

Example:

{
  "htmlPath": "./sample.html",
  "outputPath": "./output.pdf",
  "format": "A4",
  "printBackground": true,
  "marginTop": "10mm",
  "marginBottom": "10mm"
}

Direct Testing

npx tsx test-conversion.ts

Documentation

MCP_USAGE.md - Complete guide for using with Claude Code/Desktop
REQUIREMENTS.md - System requirements and installation
mcp-config-example.json - Example configuration file

Architecture

html2pdf-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── pdf-converter.ts   # Puppeteer PDF conversion logic
│   └── types.ts           # TypeScript type definitions
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Technical Details

Browser Instance Pooling

The server maintains a reusable browser instance to improve performance for multiple conversion requests. The browser is automatically launched on first use and cleaned up on server shutdown.

Rendering Process

Launch headless Chrome via Puppeteer
Load HTML content (from file or string)
Wait for page load or network idle
Execute any JavaScript on the page
Generate PDF with specified options
Clean up page resources

Error Handling

File access validation
Timeout handling (default 30s)
Browser crash recovery
Graceful resource cleanup

Performance Considerations

First PDF generation: ~1.5-2s (includes browser launch)
Subsequent conversions: ~0.5-1s (reuses browser instance)
Memory usage: ~100-200MB per browser instance
Recommended for batch processing with the same server instance

Sample Output

Sample files included in the repository:

sample.html → sample.pdf

Features demonstrated:

📊 Chart.js integration with dynamic data visualization
🇰🇷 Korean + 🇬🇧 English bilingual content
✅ Emoji support (✅ ⚠️ 📈 🎯 💡 etc.)
🎨 Modern CSS styling with gradients and shadows
📱 Responsive tables and grid layouts
💼 Professional business report format

Conversion results:

Processing time: 2.3s
Output file size: 896.63 KB
Format: A4 portrait with 80% scale
Full CSS styling and fonts preserved

Requirements

Node.js 18+
Chrome/Chromium (automatically downloaded by Puppeteer)
Korean/CJK Fonts (required for Korean text support)

Installing Korean Fonts

Amazon Linux / RHEL / Fedora

# Korean fonts
sudo yum install -y google-noto-sans-cjk-kr-fonts google-noto-serif-cjk-kr-fonts

# Emoji fonts (optional, recommended)
sudo yum install -y google-noto-emoji-color-fonts google-noto-emoji-fonts

# Update font cache
fc-cache -fv

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra fonts-noto-color-emoji
fc-cache -fv

See REQUIREMENTS.md for complete system requirements and troubleshooting.

License

MIT