Markdown2PDF MCP Server (markdown2pdf-mcp)

Markdown2PDF MCP 服务（markdown2pdf-mcp）

用于将 Markdown 文档转换为 PDF 文件的 MCP 服务。该服务提供了一种简单高效的方式，可从 Markdown 内容生成 PDF，并支持语法高亮、自定义样式、可选页码，以及灵活的水印位置（仅首页或所有页面）。

灵感来自 Alan Shaw 的 markdown-pdf。

功能

• 通过单条命令将 Markdown 转换为 PDF
• 高性能批量转换，共用单个浏览器会话（batch_create_pdf）
• 无需启动浏览器，即可进行转换前的 Markdown 校验和 lint 检查（validate_markdown）
• 内置视觉主题：default、github、academic、report 和 minimal
• 自定义 CSS 样式和字体覆盖
• 支持非对称边距（margin: { top, right, bottom, left }）
• 可从字符串或本地文件路径（inputPath）直接转换
• 代码块语法高亮
• 使用本地资源包渲染 Mermaid 图表
• 使用 Chrome 渲染引擎生成现代 PDF
• 可选页码和自定义页眉／页脚文本
• 水印范围可配置（首页或所有页面）

限制

以下 Markdown 元素不受支持：

• LaTeX 数学公式（例如，$x^2$ 或 $$\sum_{i=1}^n x_i$$）
• 复杂数学公式或科学记数法

请使用以下受支持的 Markdown 元素：

• 标题（所有级别）
• 文本格式（粗体、斜体、删除线）
• 列表（有序和无序）
• 带语法高亮的代码块
• 表格
• 引用块
• 链接
• 图片（base64 数据 URI，或 M2P_ASSETS_DIR 中的文件；参见图片）
• 任务列表
• Mermaid 图表

安全说明： 渲染完全在本地完成。Markdown 中的原始 HTML 不会被传递处理，且渲染器默认会阻止读取本地文件和发送外部请求。请参阅安全公告。

Mermaid 图表

要渲染 Mermaid 图表，请使用 mermaid 代码块：

´´´markdown

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

´´´

如果图表存在语法错误，错误消息会显示在 PDF 中，帮助你调试。你也可以在转换前运行 validate_markdown，检查 Mermaid 图表语法。

安装（从源码安装）

# Clone the repository
git clone https://github.com/2b3pro/markdown2pdf-mcp.git

# Navigate to the project directory
cd markdown2pdf-mcp

# Install dependencies
npm install

# Build the project
npm run build

安装（通过 npm）

npm install markdown2pdf-mcp

使用方法

MCP 工具概览

该服务提供三个专用工具：

1. create_pdf_from_markdown：将 Markdown 文档转换为 PDF，并提供丰富的版面、主题和边距配置。
2. batch_create_pdf：通过一次调用并共用浏览器会话，转换多个 Markdown 文档或文件。
3. validate_markdown：快速的转换前检查，无需启动浏览器，即可校验 Markdown 语法、Mermaid 代码块、资源路径和大小限制。

---

1. create_pdf_from_markdown

{
  // Content inputs (provide at least one)
  markdown?: string;        // Raw Markdown string content
  inputPath?: string;       // Or path to a local .md file on disk

  // Layout & Formatting
  outputFilename?: string;  // Target PDF path (e.g., "report.pdf", "out/q3.pdf")
  paperFormat?: string;     // 'letter' (default), 'a4', 'a3', 'a5', 'legal', 'tabloid'
  paperOrientation?: string;// 'portrait' (default), 'landscape'
  paperBorder?: string;     // Uniform border margin (e.g., '20mm', '1.5in')
  margin?: {                // Asymmetric margins (overrides paperBorder)
    top?: string;
    right?: string;
    bottom?: string;
    left?: string;
  };

  // Themes & Styling
  theme?: string;           // 'default', 'github', 'academic', 'report', 'minimal'
  customCss?: string;       // Custom CSS injected into the page

  // Header, Footer & Watermark
  watermark?: string;       // Watermark text (max 15 characters, uppercase)
  watermarkScope?: string;  // 'all-pages' (default) or 'first-page'
  showPageNumbers?: boolean;// Show page numbers in footer (default: false)
  headerText?: string;      // Custom running header text
  footerText?: string;      // Custom running footer text
}

使用主题和自定义边距的示例：

await use_mcp_tool({
  server_name: "markdown2pdf",
  tool_name: "create_pdf_from_markdown",
  arguments: {
    markdown: "# Quarterly Report\n\nKey performance highlights...",
    outputFilename: "q3-report.pdf",
    theme: "report",
    paperFormat: "a4",
    margin: { top: "25mm", right: "15mm", bottom: "25mm", left: "15mm" },
    showPageNumbers: true,
    headerText: "Confidential - Executive Eyes Only",
  },
});

---

2. batch_create_pdf

通过一次调用并复用浏览器实例，转换多个文档：

await use_mcp_tool({
  server_name: "markdown2pdf",
  tool_name: "batch_create_pdf",
  arguments: {
    documents: [
      { markdown: "# Chapter 1\nIntroduction...", outputFilename: "ch1.pdf" },
      { inputPath: "docs/ch2.md", outputFilename: "ch2.pdf" },
      { markdown: "# Appendix\nData sheets...", outputFilename: "appendix.pdf", theme: "academic" }
    ],
    sharedConfig: {
      paperFormat: "letter",
      theme: "github",
      showPageNumbers: true
    }
  }
});

---

3. validate_markdown

启动 PDF 转换前的快速检查：

await use_mcp_tool({
  server_name: "markdown2pdf",
  tool_name: "validate_markdown",
  arguments: {
    markdown: "# My Document\nFormula: $x^2$\n```mermaid\ngraph TD; A-->B;\n```"
  }
});

返回文档统计信息、警告（例如，不受支持的 LaTeX 数学公式或被移除的 HTML 标签）以及错误（例如，失效的图片引用或超大文件）。

## Running on Demand with `npx`

You can run the server without a permanent local install by asking `npx` to grab the latest package and execute its entrypoint:

```bash
npx -y markdown2pdf-mcp@latest

此命令会将软件包安装到临时工作区，然后通过其捆绑的 CLI 启动 MCP 服务。将 MCP 客户端（例如 Cline 或 Claude Desktop）指向此命令，即可按需启动服务。

配置

输出目录

对于使用 MCP 的应用（如 Cline 或 Claude），你可以在 MCP 设置文件中配置输出目录。如果未配置，文件将保存到 $HOME：

{
  "mcpServers": {
    "markdown2pdf": {
      "args": ["/path/to/markdown2pdf-mcp/build/index.js"],
      "env": {
        "M2P_OUTPUT_DIR": "/path/to/output/directory"
      }
    }
  }
}

M2P_OUTPUT_DIR 是默认位置。outputFilename 中的路径优先级更高：绝对路径将按原样使用，相对路径（例如 reports/q3.pdf）则放在 M2P_OUTPUT_DIR 下（如果未设置，则放在 $HOME 下）。

工具会自动处理文件名冲突，方法是追加递增的数字（例如 output.pdf、output-1.pdf、output-2.pdf）。

图像

出于安全考虑，渲染器不会加载任意本地路径或外部 URL 中的图像。你有以下三个选项：

1. Base64 数据 URI 无需配置即可在任何地方使用：![logo](data:image/png;base64,iVBORw0...)

2. 资源目录。 设置 M2P_ASSETS_DIR，并通过相对路径引用图像。只有解析到该目录内的文件才能加载；../ 路径遍历、指向目录外部的符号链接，以及其他位置的绝对路径都会被拦截。

   "env": {
     "M2P_ASSETS_DIR": "/path/to/images"
   }
   

   ![Q3 revenue](charts/q3.png)
   

3. 手动覆盖（不安全）。 使用 --dangerously-allow-images 启动服务（或设置 M2P_DANGEROUSLY_ALLOW_ALL_IMAGES=true），即可像 2.2.0 之前的版本一样，从任何本地路径或 URL 加载图像。这会重新引入安全公告中描述的文件泄露和 SSRF 问题，因此只有在服务接收的所有 Markdown 内容都完全可信时才使用。无论采用哪种方式，原始 HTML 始终处于禁用状态。

   "args": ["/path/to/markdown2pdf-mcp/build/index.js", "--dangerously-allow-images"]
   

大文件支持

该工具会自动处理大型 Markdown 文件，支持：

• 动态超时： 根据内容大小自动调整（对于超大文件，最长可达 5 分钟）
• 内存限制： 为 Chrome 分配 4GB 内存，以处理复杂文档
• 大小验证： 文件大小上限为 10MB，并提供清晰的错误消息
• 进度跟踪： 显示内容大小和预计处理时间

对于超大文件（1300 行以上），该工具将：

1. 提醒你处理时间可能较长
2. 自动延长超时时间
3. 在响应中显示内容大小
4. 在处理失败时提供详细的错误消息

详细日志记录

启用详细日志以进行调试：

{
  "mcpServers": {
    "markdown2pdf": {
      "command": "node",
      "args": ["/path/to/markdown2pdf-mcp/build/index.js"],
      "env": {
        "M2P_OUTPUT_DIR": "/path/to/output/directory",
        "M2P_VERBOSE": "true"
      }
    }
  }
}

此操作会将处理步骤记录到 stderr，不会干扰 MCP 通信。

更倾向于使用本地构建的版本？将 "command" 改回 node，并将 "args" 指向已编译的 build/index.js 路径，而不是使用 npx。例如："args": ["/path/to/markdown2pdf-mcp/build/index.js"]。

依赖项

• @modelcontextprotocol/sdk - 用于实现服务的 MCP SDK
• remarkable - Markdown 解析器
• highlight.js - 语法高亮
• puppeteer - 使用 Chrome for Testing 生成现代 PDF（v131.0.6778.204）

Chrome 版本

此软件包使用 Chrome v131.0.6778.204，确保所有安装环境生成的 PDF 保持一致。运行 npm install 时会自动安装此版本。

• tmp - 临时文件处理

开发

# Build the project
npm run build

# Start the server
npm start

---

支持

Markdown2PDF MCP 免费且开源。如果它帮你节省了将 Markdown 转换为精美 PDF 的时间，不妨请我喝杯咖啡、吃个羊角面包！这有助于持续推出更新。

请我喝杯咖啡、吃个羊角面包！

---

许可证

MIT

贡献

1. Fork 此仓库
2. 创建你的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将更改推送到该分支（git push origin feature/amazing-feature）
5. 创建 Pull Request