quillpdf-mcp

quillpdf-mcp

用于 PDF 操作的 MCP 工具。一个用于本地 PDF 处理的 MCP 服务和命令行工具：

• 合并、拆分、整理、删除页面
• 旋转、裁剪
• 添加水印、Bates 编号、页码
• 展平表单、将图像转换为 PDF
• 清理元数据、统计页数
• 使用 AES-256 加密／解锁

基于 pdf-lib 构建。采用 MIT 许可证。使用 stdio 传输。不会进行网络调用——文件不会离开你的设备。

安装

npx -p quillpdf-mcp quillpdf --help   # CLI
npx quillpdf-mcp --help               # MCP server (your MCP client launches it over stdio)

或全局安装：

npm install -g quillpdf-mcp
quillpdf --help

需要 Node.js 18+。

范围

quillpdf-mcp 实现 PDF 结构转换和 AES-256 加密／解锁。它不执行 OCR、涂黑或压缩——这些功能可在浏览器版本中使用（quillpdf.com），处理过程同样只在客户端进行。只有在能够完全本地运行时，这些功能才会加入此处。

在 MCP 客户端中使用

quillpdf-mcp 适用于任何 MCP 客户端。它是一个 stdio 服务，因此每个客户端都需要同样的内容：一个用于启动服务的命令。将此服务条目添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "quillpdf": {
      "command": "npx",
      "args": ["-y", "quillpdf-mcp"]
    }
  }
}

客户端示例

该条目应放置的位置（请查看客户端文档了解当前路径）：

• Claude Desktop — claude_desktop_config.json（Settings > Developer > Edit Config）。在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json。使用与上文相同的 mcpServers 块。(文档)

• Claude Code — 运行 claude mcp add quillpdf -- npx -y quillpdf-mcp，或将此配置块放入项目根目录的 .mcp.json。(文档)

• Cursor — 在项目中使用 .cursor/mcp.json，或使用 ~/.cursor/mcp.json 应用于所有项目。使用相同的 mcpServers 块。(文档)

• VS Code — 在工作区中使用 .vscode/mcp.json，或为你的配置文件运行 MCP: Open User Configuration。VS Code 使用 servers 键而不是 mcpServers，并且需要 "type": "stdio"：

  { "servers": { "quillpdf": { "type": "stdio", "command": "npx", "args": ["-y", "quillpdf-mcp"] } } }
  

  (文档)

然后可以向助手提出类似 “将 invoice-1.pdf 和 invoice-2.pdf 合并为 combined.pdf” 或 “为 discovery.pdf 添加 Bates 编号，前缀为 ABC，起始编号为 1。” 的请求。助手会提供你设备上的文件路径；服务会在本地读取和写入文件。

可直接复制的配置位于 examples/mcp-config.json。

工具

工具	功能
pdf_merge	按顺序将 2 个或更多 PDF 合并为一个文件
pdf_split	按页码范围拆分（每组生成一个文件），或将指定页面提取到一个文件中
pdf_rotate	将页面旋转 90° 的倍数（所有页面或选定页面）
pdf_watermark	在每页加盖文字（大小／不透明度／颜色／位置）
pdf_bates	添加连续 Bates 编号（前缀、起始编号、补零、角落位置）
pdf_clean_metadata	清除 info-dict 字段和日期，并删除 XMP 元数据流
pdf_page_count	统计页数
pdf_organize	按列出的顺序保留页面——一步完成重新排序、删除和复制
pdf_delete_pages	删除列出的页面，其余页面顺序不变
pdf_page_numbers	添加易读的页码（3、3 of 12、Page 3 of 12），可选不编号封面
pdf_crop	通过设置 CropBox 修剪页面边距——只隐藏，不删除（不是涂黑）
pdf_flatten	将已填写的表单值绘制到页面上，使其无法编辑或作为表单数据读取
pdf_from_images	根据 PNG/JPEG 图像生成 PDF，每页一张图像
pdf_protect	使用 AES-256 加密文档，打开时需要密码
pdf_unlock	移除你知道密码的文档的密码

在命令行中使用

# Merge (order is preserved)
quillpdf merge a.pdf b.pdf c.pdf -o combined.pdf

# Split into one file per range group → out-1.pdf (pages 1-3), out-2.pdf (page 5)
quillpdf split in.pdf --ranges "1-3,5" -o out.pdf

# Extract specific pages into a single file (reordering/duplicates allowed)
quillpdf split in.pdf --pages "5,1,1" -o extract.pdf

# Rotate every page 90°, or just some pages
quillpdf rotate in.pdf --angle 90 -o rotated.pdf
quillpdf rotate in.pdf --angle 180 --pages "2,4" -o rotated.pdf

# Watermark
quillpdf watermark in.pdf --text "DRAFT" --opacity 0.15 --position center -o wm.pdf

# Bates numbering → PLT-000001, PLT-000002, …
quillpdf bates in.pdf --prefix "PLT-" --start 1 --pad 6 -o numbered.pdf

# Strip document metadata
quillpdf clean-metadata in.pdf -o clean.pdf

# Page count (prints a number)
quillpdf page-count in.pdf

每条命令都有 --help。

现有文件绝不会被静默替换。 如果 -o 路径已存在，命令会报错并停止，而不会覆盖文件——添加 --force（或在 MCP 工具中设置 force: true）即可主动替换。

隐私与安全说明

• 仅限本地处理。 所有 PDF 处理都通过 pdf-lib 在进程内完成。服务通过 stdio 通信，绝不会建立网络连接。（MCP SDK 在 node_modules 中捆绑了可选的 HTTP/SSE 传输，但本服务始终只使用 stdio，因此这些代码都不会运行。）
• 拒绝处理受密码保护的 PDF，不会静默解锁。 除 unlock 外，所有操作都会停止并给出明确提示，不会替你移除密码。unlock 只会使用你提供的密码解密——不会恢复、猜测或暴力破解密码。
• 加密引擎。 protect 和 unlock 会在进程内运行编译为 WebAssembly 的 QPDF（Apache-2.0），与其他所有功能一样，无需联网。pdf-lib 完全不支持加密，而支持加密的社区分支无人维护——加密是唯一一种会因细微错误而导致你以为已锁定的文档实际上并未锁定的操作，因此这里改用参考实现。
• 仅支持 AES-256。 protect 会生成 PDF 2.0 加密修订版 6。我们有意不提供 40 位和 128 位模式：QPDF 都将其归类为弱加密，而发布一个无法提供有效保护的“受保护”文件，还不如什么都不发布。
• 权限标志只是请求，并非保证。 --no-print / --no-copy / --no-modify 会设置行为良好的阅读器会遵守的标志位；加密本身并不会强制执行这些限制。真正保护文件的是密码。（即使设置了 --no-copy，仍允许为无障碍目的提取内容，以便屏幕阅读器正常工作。）
• 裁剪不等于涂黑。 crop 会设置 CropBox，因此被裁掉的内容只是隐藏了，仍保留在文件中，并且可以完整恢复。不要用它来移除敏感内容。
• clean-metadata 的范围。 它会清除文档信息字典中的标题、作者、主题、关键词和创建者字段，以及 CreationDate/ModDate，并且删除文档级 XMP 元数据流——这是 Acrobat、Word、InDesign 和 LibreOffice 写入的副本，通常才是权威版本。请注意，pdf-lib 保存时会用自己的标记重写 /Producer 字段，因此该字段是被替换，而非清空。它不会清除页面级批注、嵌入的文件附件，也不会处理页面中的文本或图像内容。

暂未提供（路线图）

这些功能需要 Node 图像后端或 OCR 引擎，计划在后续版本中推出——目前尚未包含在此软件包中：

• compress（图像重新编码）——需要 sharp 等图像编解码器
• pdf-to-image（将页面渲染为 PNG）——需要光栅化器（pdfjs-dist + canvas）
• redact（通过光栅化真正移除涂黑内容）——需要同一光栅化器
• ocr（可搜索文本层）——需要 tesseract.js

每项功能都会让此软件包的依赖范围大约扩大四倍，这正是我们暂缓推出它们的原因：这里的定位是提供小巧、本地运行、无需联网的工具。只有在能够完全在本地运行，且不牺牲这一点时，它们才会推出。

理念

保持服务小巧、本地运行且易于审查。大多数“PDF API”工具处理文档时都会说“上传给我们”——对于法律调查取证、医疗记录或财务文件来说，上传本身就是问题。本工具在你的设备上运行，数据始终留在你的磁盘中。

开发

npm install
npm run build     # tsc → dist/
npm test          # builds, then runs the unit suite (node:test)

引擎（src/core.ts）是纯函数：输入字节，输出字节，不执行 I/O。CLI（src/cli.ts）和 MCP 服务（src/server.ts）是基于它构建的轻量前端。

许可证

MIT © Purple Directive。详见 LICENSE。

了解更多信息，请访问 quillpdf.com。