HTML to PDF MCP Server

HTML转PDF MCP服务器

MCP（模型上下文协议）服务器，用于使用Puppeteer的浏览器渲染引擎将HTML文件或HTML内容转换为PDF。

特性

• 通过高保真浏览器渲染将HTML文件转换为PDF
• 将HTML内容字符串转换为PDF
• 完全支持CSS和JavaScript
• 可配置的页面格式、边距、方向
• 页眉和页脚模板
• 背景图形打印
• 等待网络空闲选项
• 浏览器实例池以提高性能

安装

npm install
npm run build

用法

克劳德代码快速入门/桌面

此服务器旨在与 克劳德代码 和 克劳德桌面 作为MCP工具。

📖 有关MCP设置和使用说明的详细信息，请参阅 MCP_USAGE.md

基本MCP配置

添加到MCP客户端配置中：

克劳德代码: ~/.config/claude-code/mcp_config.json 克劳德桌面: ~/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"
    }
  }
}

配置完成后，重启Claude并询问：

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

可用工具

convert_html_to_pdf

使用浏览器渲染将HTML转换为PDF。

参数：

• htmlPath （字符串，可选）：要转换的HTML文件的路径
• htmlContent （string，可选）：要转换的HTML内容字符串（htmlPath的替代品）
• outputPath （字符串，可选）：输出PDF文件路径（默认：随时间戳自动生成）
• format （字符串，可选）：纸张格式-A4、A3、Letter、Legal、Tabloid（默认：A4）
• landscape （布尔值，可选）：使用横向（默认值：false）
• printBackground （布尔值，可选）：打印背景图形（默认值：true）
• scale （数字，可选）：网页渲染比例，0.1-2（默认值：1）
• marginTop （字符串，可选）：上边距（默认值：10mm）
• marginBottom （字符串，可选）：底部边距（默认值：10mm）
• marginLeft （字符串，可选）：左边距（默认值：10mm）
• marginRight （字符串，可选）：右边距（默认值：10mm）
• displayHeaderFooter （布尔值，可选）：显示页眉和页脚（默认值：false）
• headerTemplate （字符串，可选）：标题的HTML模板
• footerTemplate （字符串，可选）：页脚HTML模板
• waitForNetworkIdle （布尔值，可选）：等待网络空闲（默认值：false）
• timeout （数字，可选）：最长等待时间（毫秒）（默认值：30000）

例子：

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

直接测试

npx tsx test-conversion.ts

文档

• MCP_USAGE.md -与Claude Code/桌面一起使用的完整指南
• 要求.md -系统要求和安装
• mcp-config-example.json -配置文件示例

建筑

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

技术细节

浏览器实例池

服务器维护一个可重用的浏览器实例，以提高多个转换请求的性能。浏览器在首次使用时会自动启动，并在服务器关闭时进行清理。

渲染过程

1. 通过Puppeteer启动无头Chrome
2. 加载HTML内容（从文件或字符串）
3. 等待页面加载或网络空闲
4. 在页面上执行任何JavaScript
5. 使用指定选项生成PDF
6. 清理页面资源

错误处理

• 文件访问验证
• 超时处理（默认30秒）
• 浏览器崩溃恢复
• 优雅的资源清理

性能注意事项

• 第一代PDF：约1.5-2s（包括浏览器启动）
• 后续转换：~0.5-1s（重用浏览器实例）
• 内存使用量：每个浏览器实例约100-200MB
• 建议使用同一服务器实例进行批处理

示例输出

存储库中包含的示例文件：

示例.html → 样本.pdf

演示的功能：

• 📊 Chart.js与动态数据可视化的集成
• 🇰🇷 韩语+🇬🇧 英语双语内容
• ✅ 表情符号支持(✅ ⚠️ 📈 🎯 💡 等等）
• 🎨 带有渐变和阴影的现代CSS样式
• 📱 响应式表格和网格布局
• 💼 专业业务报告格式

转换结果：

• 处理时间：2.3s
• 输出文件大小：896.63 KB
• 格式：A4肖像，比例为80%
• 保留完整的CSS样式和字体

需求

• Node.js 18+
• Chrome/Chromium（由Puppeteer自动下载）
• 韩语/CJK字体 （需要韩语文本支持）

安装韩文字体

亚马逊Linux/REL/FFedora

# 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

看 要求.md 了解完整的系统要求和故障排除。

许可证

麻省理工学院