pdfedit-mcp

@niubai/pdfedit-mcp — 通过 Agent 编辑现有 PDF

通过 PDF Edit API 提供 5 个 MCP 工具：替换、删除、涂黑、插入和填写现有 PDF 中的文本，同时保留原始字体、原始布局，以及所有未指定的内容。这不是“生成一个看起来相似的新 PDF”，而是修改同一个文件中你指定的文字，并提供每项更改的前后对比图。

未设置 PDFEDIT_BASE_URL 时，服务会连接托管 API https://api.niubai.vip；设置该变量即可指向其他部署。

30 秒快速试用，无需密钥

未设置 PDFEDIT_API_KEY 时，服务会使用无需密钥的免费套餐：每个 IP 每天可处理 20 页，输出会带有 TEST 水印，本地文件也包括在内。

Claude Code

claude mcp add pdfedit -- npx -y @niubai/pdfedit-mcp

Cursor / VS Code / Claude Desktop — 添加此服务条目（或使用仓库页面上的按钮）：

{ "pdfedit": { "command": "npx", "args": ["-y", "@niubai/pdfedit-mcp"] } }

然后向 Agent 提出请求：“将 ./contract.pdf 中的 ‘Acme Ltd’ 替换为 ‘Acme GmbH’，并涂黑 IBAN。” 编辑后的 PDF 会写入原文件所在目录，并返回每项更改的前后对比图。只需提供一个邮箱，即可获取免费 API 密钥（每月 200 页，普通文档无水印），请访问 https://api.niubai.vip。

安装

Claude Code — 一行命令：

claude mcp add pdfedit -e PDFEDIT_API_KEY=sk_live_your_key -- npx -y @niubai/pdfedit-mcp

Cursor — 使用 deeplink（也可以在 Settings → MCP 中添加相同的 JSON）：

cursor://anysphere.cursor-deeplink/mcp/install?name=pdfedit&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBuaXViYWkvcGRmZWRpdC1tY3AiXSwiZW52Ijp7IlBERkVESVRfQVBJX0tFWSI6InNrX2xpdmVfeW91cl9rZXkifX0=

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "pdfedit": {
      "command": "npx",
      "args": ["-y", "@niubai/pdfedit-mcp"],
      "env": {
        "PDFEDIT_API_KEY": "sk_live_your_key"
      }
    }
  }
}

没有密钥？请省略 env：无需密钥的免费套餐每个 IP 每天可处理 20 页，输出会带有 TEST 水印。无法运行本地服务的 Web 客户端（如 claude.ai）可以改为添加托管端点；该端点仅接受 PDF URL。

本地文件与 URL

此软件包在你的计算机上运行，因此每个工具的 file 参数都可以接受绝对本地路径（或 ~ 路径）——服务会为你上传文件，并将编辑后的 PDF 写回输入文件所在目录，命名为 <name>.edited.pdf——也可以接受 https:// URL，或之前调用返回的 f_… 文件 ID。托管的 Streamable-HTTP 端点无法读取你的磁盘，并会提示这一点（远程服务无法读取本地路径；请传入 URL）。无论使用哪种方式，PDF 都不会以 MCP 内容 Blob 的形式传输；只有最多 3 张已更改页面的预览 PNG 会以内联形式返回。

工具

工具	功能
pdf_edit	一次调用即可替换、删除、涂黑、插入或填写内容，并返回预览。
pdf_batch	对一个模板中的每条记录执行相同编辑。返回任务 ID。
pdf_find	返回包含页码、bbox、字体和 span ID 的所有文本片段；可使用 4 种匹配模式筛选。
pdf_preview	将页面（或区域）渲染为 PNG，并可选择显示高亮框。
pdf_job	返回异步编辑或批处理的结果。

每个架构都由网关的 OpenAPI 文档生成，因此此处的 edits[] 条目与 POST /v1/edit 及各 SDK 使用的条目完全一致，详见 src/tools.ts。

拒绝处理的情况及原因

引擎宁愿说明原因并返回“否”，也不会交付一个看似已编辑、实际却并非如此的文件。拒绝处理的情况分为两类。

校验关卡 — 编辑已尝试并回滚

每项更改都会先写入，再检查，然后保留或撤销。未通过任何关卡的编辑组都会回滚，并记录在 failed[] 中：

原因	发生了什么
collateral_damage	重写区域以外的像素发生了变化——页面上的其他内容移动了。页面已逐字节恢复。
readback_failed	重新读取编辑后的矩形区域时，返回的文本与预期内容不符。
does_not_fit	替换内容无法放入该区域，且不允许通过 fit 让情况变得更糟（fit: "strict"）；或者插入内容会覆盖已有文本。
font_unavailable	options.font.policy: "exact_only"（或 "metric_only"），且系统和文档中都没有可接受的字体。
redact_residual	遮盖后，矩形区域内的字符串仍可读——因此拒绝移除，而不会报告操作已完成。
no_target、field_not_editable、field_value_invalid、field_value_mismatch	表单字段不存在、为只读、拒绝该值，或回读结果与写入值不符。

使用 options.atomic（默认值）时，任何单项失败都会导致整个请求失败，且不会生成文件；options.strict 对未匹配到的编辑也会采取相同处理。未匹配到的编辑会返回模糊匹配的 suggestions（“你是不是想找 Acme, Inc.？”），而不是静默地不做任何处理。

已知不支持的操作 — 将作为 invalid_request 预先拒绝

API 会在触碰文档之前拒绝以下操作：

• 在 find 中使用从右向左书写的文本（阿拉伯语、希伯来语）。匹配器之后的所有处理都是从左向右的：文本行从左侧开始组装，替换内容向右排布，因此 RTL 文本会与视觉上颠倒的行进行匹配，并以错误方向写入，后续流程也无法察觉。
• 对仅以扫描像素形式存在的文本执行 redact。 单词本身就是图像；遮盖后它仍留在文件中，因此无法兑现该操作的承诺。
• 将 style 与 fit: "reflow" 一起使用。 重新排版会使用文档自身的字体重排整个段落，因此匹配到的短语不再有独立的文本片段可供设置样式。
• 在 redact 或 form 上使用 fit: "reflow"。
• 使用 options.preview: "pages"（整页预览）；"changes" 和 "none" 可用。
• 未知操作。

已知限制 — 均受支持，但有一些注意事项

• 栅格 OCR 写入会生成图像，而非文本。 如果扫描行没有可供克隆的底层文本，新文字会以像素形式绘制：页面上的内容正确，经重新渲染验证，但之后无法选择或搜索。
• 扫描件上的涂黑会通过文本层和像素清除进行验证，而不是通过再次识别输出内容来验证。
• 相对定位的文本 — matplotlib 会将每个刻度的位置设为相对于前一个刻度 — 可能导致无关元素移动数百点。引擎会将其视为附带损坏，并回滚更改；页面保持正确，但编辑不会生效。语料库中有一个文件故意这样设置，用作回归测试。
• 字体。 如果文件嵌入的字体足够完整（该字体任意页面上的子集均算），替换文字会使用文档自身的字体；否则会使用度量兼容的近似字体（Arial、Helvetica、Times New Roman、Courier New、Calibri、Cambria、Georgia、Segoe UI、Palatino、Book Antiqua、Bookman、Century Gothic、Avant Garde、New Century Schoolbook 和 Arial Narrow 均有此类字体：字宽相同，因此行尾位置不变）；最后才会使用同类的相似字体。结果始终会说明具体字体（font_source、font_used）；如果使用了最后一种方案，摘要会明确列出 approx_font_used；而 options.font.policy: "metric_only" 会直接拒绝这种方案。因此，“看起来略有不同”会是一个可读取的值，而非意外。
• 对单选按钮组和组合框使用 flatten 取决于文件自带的外观；如果无法处理，字段会保持可交互，并发出 flatten_skipped 警告，而不会失败。
• 加密文档需要打开密码（password）；未提供密码时不会尝试编辑。

更多信息

• 快速入门 — 按客户端安装、告诉 Agent 什么，以及会得到什么。这是规范的使用文档；本 README 有意保持简短。
• API 参考 — edits[]、options 和响应中的每个字段。
• 示例 — 十组修改前后对照，每组都附有生成结果的请求。
• 代码仓库 — 此服务、SDK 和托管端点的源代码。

MIT。API 背后的引擎采用 AGPL-3.0；API 会通过 GET /source 向用户提供完整源代码（任何密钥均可，免费测试密钥也包括在内；托管的 MCP 端点会将请求转发至 https://pdfedit-mcp-remote.niubai-pdfedit-remote-worker.workers.dev/source）。