Pdf Toolkit Mcp

PDF Toolkit MCP

💼 承接 MCP/AI 集成自由职业项目 — 请私信 @aryansalian03，或通过 aryanbv.com 联系

一款适用于任何 MCP 客户端、支持写入的 PDF 工具包。它提供 22 个工具，用于读取、创建、渲染、转换和保护 PDF。其中包括将页面渲染为图像，以便视觉模型读取扫描文档；根据 Markdown 或结构化数据构建 PDF；使用 AES-256 加密；以及保留表单字段的合并和拆分操作。它没有原生依赖，因此只需一条 npx 命令即可在本地运行。

npx -y @aryanbv/pdf-toolkit-mcp

它不需要配置文件、API 密钥、Docker 或编译器，并且可以离线运行。

概览

大多数 MCP PDF 服务只能读取 PDF。这个服务还支持写入：它可以根据 Markdown 或结构化数据创建文档、填写并扁平化表单、重新编排页面结构，以及应用 AES-256 加密，整个过程无需原生构建工具链。

以下几点值得了解：

• 它能读取扫描件。pdf_render_pages 会将页面栅格化为图像，因此具备视觉能力的模型可以读取没有文本层的扫描版或纯图像 PDF。
• 合并、拆分、重排和删除操作会保留 AcroForm 字段，而不是将其丢弃。不同输入中发生冲突的名称会按来源分别添加命名空间；每次调用都会报告保留、重命名或丢弃的内容。
• 它通过 qpdf 实现 AES-256 加密，而不是使用旧版 RC4 方案。
• 所有引擎均采用 WASM 或纯 JavaScript，因此 npx 可在 Node 20 及更高版本的 Windows、macOS 和 Linux 上运行，无需 node-gyp、canvas 绑定或预编译二进制文件。
• 错误包含稳定代码，堆栈跟踪仅在内部保留；超出页面范围的放置操作会被拒绝，而不会被静默裁剪；大型响应会被截断，同时确保 JSON 格式不受破坏。

客户端配置

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

claude mcp add pdf-toolkit -- npx -y @aryanbv/pdf-toolkit-mcp

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "servers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

连接后，用日常语言描述你的需求，客户端会选择合适的工具并填写参数。下方的 JSON 代码块展示了各工具接受的参数，供你参考。

工具

从 Markdown 创建 PDF

一键将 Markdown 转换为多页 PDF。支持 CommonMark 和 GFM：标题、粗体和斜体、表格、有序列表和无序列表、围栏代码块以及引用块，并使用 @react-pdf/renderer 渲染。

“根据这份 Markdown 报告创建 PDF。”

pdf_create_from_markdown 参数：

{
  "markdown": "# Quarterly Report\n\nRevenue grew **23% YoY**.\n\n| Region | Q1 2025 | Q1 2026 |\n|--------|---------|--------|\n| Americas | $1.2M | $1.5M |\n| EMEA | $800K | $960K |\n\n## Key Wins\n\n1. 12 new enterprise contracts\n2. Churn down to 3.1%",
  "outputPath": "/path/to/report.pdf",
  "pageSize": "Letter"
}

表格列宽会根据内容调整，并遵循对齐方式；嵌套列表会缩进，较长的代码行会自动换行。之后可使用 pdf_add_page_numbers 添加页码。

模板

使用 invoice、report 和 letter 模板，根据结构化数据生成文档。

“为 Riverbend Outfitters 创建一张发票。”

pdf_create_from_template 参数：

{
  "templateName": "invoice",
  "data": {
    "companyName": "Northpoint Design",
    "clientName": "Riverbend Outfitters",
    "invoiceNumber": "2026-0042",
    "invoiceDate": "2026-04-01",
    "items": [
      { "description": "Website redesign", "quantity": 40, "unitPrice": 150 },
      { "description": "Annual hosting", "quantity": 1, "unitPrice": 299 }
    ],
    "taxRate": 18,
    "currency": "USD",
    "paymentTerms": "Net 30"
  },
  "outputPath": "/path/to/invoice.pdf"
}

invoice 模板的可选参数 currency 可接受 ISO 代码或符号。WinAnsi 兼容的符号（$ € £ ¥）会作为字形渲染；Helvetica 无法绘制的代码（例如 INR、KRW 或 TRY）会回退为 ISO 代码标签（INR 20.00），因此任何货币都能正常使用，不会报错。pdf-toolkit://templates 资源列出了所有模板及其接受的字段。

读取扫描版和纯图像 PDF（视觉）

许多 PDF 是扫描件，没有文本层。pdf_render_pages 会将页面栅格化，以便具备视觉能力的客户端读取。

“读取这份扫描版合同。”

内联模式会将页面作为图像返回，供模型直接读取（最多 5 页；DPI 会自动限制，以保护上下文窗口）：

{ "filePath": "/path/to/scanned.pdf", "inline": true }

也可以将图像文件写入磁盘（默认 150 DPI，前 50 页，PNG）：

{
  "filePath": "/path/to/scanned.pdf",
  "pages": "1-3",
  "dpi": 200,
  "format": "jpeg",
  "outputDir": "/path/to/output"
}

将 PDF 转换为 Markdown

“将 report.pdf 转换为 Markdown，以便我进行总结。”

pdf_to_markdown 根据文本位置重建阅读顺序。它最多聚合两列正文（另加全宽标题和页脚区域），根据字号推断标题，并检测列表。此工具最适用于清晰的数字版 PDF；扫描件请使用 pdf_render_pages。默认返回前 10 页。

{ "filePath": "/path/to/report.pdf", "pages": "1-5" }

搜索和比较

“查找 contract.pdf 中所有提及‘indemnification’的地方。”

pdf_search 参数：

{
  "filePath": "/path/to/contract.pdf",
  "query": "indemnification",
  "caseSensitive": false
}

每个匹配项都会返回页码和周边摘录。默认按字面进行不区分大小写的子串匹配；设置 caseSensitive: true 可区分大小写。此处有意不提供正则表达式搜索，因为攻击者提供的模式可能导致灾难性回溯（ReDoS），而单线程 JavaScript 无法可靠地中断此类操作。安全的正则表达式计划在后续版本中推出。

“v1.pdf 和 v2.pdf 之间有哪些变化？”

pdf_compare 参数：

{ "filePathA": "/path/to/v1.pdf", "filePathB": "/path/to/v2.pdf" }

此工具会报告逐页文本差异（added 和 removed），并在文本匹配时设置 identical: true。差异仅针对文本，因此不会检测纯视觉变化。

保留表单的合并、拆分、删除和扁平化

合并、拆分、重新排序和删除页面时，会保留 AcroForm 字段。不同输入中名称冲突的字段会按来源添加命名空间；每个工具都会返回 { preserved, renamed, dropped }，其中 renamed 是 { from, to } 配对列表（之后可使用字段的 to 名称引用重命名后的字段）。这些工具和 pdf_flatten 还会返回一个 flattened 布尔值。

“合并这三份表单并扁平化结果。”

pdf_merge 参数：

{
  "filePaths": ["/path/a.pdf", "/path/b.pdf", "/path/c.pdf"],
  "outputPath": "/path/merged.pdf",
  "flatten": true
}

“从 report.pdf 中删除第 2 页和第 5 页。”

pdf_delete_pages 参数：

{
  "filePath": "/path/report.pdf",
  "pages": "2,5",
  "outputPath": "/path/trimmed.pdf"
}

单独使用 pdf_flatten 可将现有表单的值烘焙为静态内容。输出路径必须与输入路径不同。

加密

“使用密码‘secure123’加密 report.pdf。”

加密采用 AES-256。可分别设置用户（打开）密码和所有者（编辑）密码，以便精细控制访问权限；如果未提供所有者密码，则默认使用用户密码。

pdf_encrypt 参数：

{
  "filePath": "/path/report.pdf",
  "outputPath": "/path/report-encrypted.pdf",
  "userPassword": "secure123",
  "ownerPassword": "admin456"
}

二维码和条形码

“在第 1 页添加一个指向我们网站的二维码。”

pdf_embed_qr_code 支持 QR Code、Code128、DataMatrix、EAN-13、PDF417 和 Aztec。位置和大小均可配置，会保留编码制式的宽高比，放置位置会考虑页面旋转，超出页面的放置请求会被拒绝，而不是裁切。

引导式提示词

该服务提供五个 MCP 提示词，用于指导客户端执行多步工作流：

资源

pdf-toolkit://templates 是一个 JSON 资源，列出 pdf_create_from_template 可用的模板及每个模板接受的字段。

尝试使用自然语言

• “根据这份 Markdown 报告创建 PDF”
• “为 Riverbend Outfitters 生成一张发票，包含 10 小时的咨询服务，每小时 $150”
• “将 january.pdf 和 february.pdf 合并为 q1-combined.pdf”
• “将此 PDF 转换为 Markdown，以便我进行摘要”
• “渲染这份扫描版 PDF，以便你能读取”
• “在 contract.pdf 中搜索 ‘termination’”
• “比较 draft-v1.pdf 和 draft-v2.pdf”
• “在 application.pdf 中将 Name 字段填写为 ‘John Doe’”
• “为 draft.pdf 添加 CONFIDENTIAL 水印”
• “使用 AES-256 密码 ‘budget2026’ 加密 financials.pdf”
• “在封面页嵌入一个带有我们网址的二维码”
• “将 report.pdf 的页面顺序调整为 3,1,2”

错误和输出语义

• 带代码的错误。 验证和加载失败时会抛出带有稳定代码的 PdfError，并以 Error [CODE]: message 的形式呈现（例如 FILE_NOT_FOUND、NOT_A_PDF、PAGE_OUT_OF_RANGE、ENCRYPTED_PDF、RESOURCE_LIMIT）。客户端可以根据代码进行分支处理，而无需解析消息文本；堆栈跟踪绝不会泄露。
• 写入工具的输出。 写入工具会在 outputPath 创建文件，并以文本形式返回该路径及文件大小，因为 MCP 没有文件内容类型。outputPath 可以指定现有文件，且该文件会被覆盖，因此请选择不会覆盖需要保留文件的路径。
• 对 JSON 安全的截断。 响应上限为 25,000 个字符。对象载荷会返回有效的 { truncated, note, preview } 封装，而不会在令牌中途截断为字符串，因此客户端的 JSON.parse 不会出错。

已知限制

• 合并、拆分、重新排序、删除。 表单字段会保留，名称冲突时会使用命名空间，并在 renamed 中以 { from, to } 对的形式报告。无法安全重建的特殊表单会在 dropped 中报告，而不会导致操作失败。
• 文本提取。 返回 PDF 流顺序，而非视觉阅读顺序。需要按阅读顺序处理时，请使用 pdf_to_markdown；原始的 pdf_extract_text 可能会交错排列多栏布局中的文本。
• PDF 转 Markdown。 最多重建两栏内容（以及通栏标题和页脚区域）；三栏或更多栏的页面会退回到单栏阅读顺序。此功能最适用于清晰的数字 PDF。表格内容会按阅读顺序输出为定位文本，而不会重建为 Markdown 表格。
• Markdown 转 PDF。 支持 CommonMark 和 GFM（标题、粗体和斜体、链接、列表、表格、围栏代码、引用块和水平线）。不支持原始 HTML、任务列表复选框状态、脚注和代码语法高亮。
• 比较。 仅比较文本；不会检测不改变文本的视觉或布局变化。
• 嵌入图像。 仅支持 JPEG 和 PNG。页面外的图像位置会触发带错误代码的错误，而不会被静默裁切。
• 字体。 内置字体仅支持拉丁字符（WinAnsi）。对于阿拉伯语、CJK 或天城文等非拉丁文字，请通过 fontPath 将 .ttf 或 .otf 文件传给 pdf_fill_form 或 pdf_create。Markdown 和模板 PDF 默认使用 Helvetica。

技术栈

采用多引擎设计。所有引擎均为纯 WASM 或 JavaScript：

要求

• Node.js 20 或更高版本。Node 18 和 20.x 系列已结束生命周期，因此推荐使用 Node 22 或 24 LTS。

开发

npm install        # install dependencies
npm run build      # compile TypeScript
npm test           # run the vitest suite (160 tests)
npm run test:cov   # tests with coverage
npm run lint       # ESLint
npm run format     # Prettier
npm run inspect    # MCP Inspector (requires Node >= 22.7.5)

请参阅 CLAUDE.md，了解架构和贡献说明。

许可证

MIT