pdfops-mcp

pdfops-mcp

由 PDFops API 提供支持的 MCP 服务，为 AI Agent 提供确定性的 PDF 工具：检查 AcroForm 字段、填写表单、合并 PDF，以及生成发票——无需 Chromium、无需原生依赖，也无需托管任何内容。

在本地 Agent 旁运行时，工具通过文件路径操作，因此 PDF 字节不会经过模型上下文：你的 Agent 说 “填写 /tmp/form.pdf 并保存到 /tmp/out.pdf”，然后会收到一行确认信息。每个 PDF 输入也接受 https:// URL 或 data:application/pdf;base64,… URI；每个输出也都可以直接内联返回，而不是写入文件——这使服务能够在托管运行时中运行（见下文）。

安装

Claude Code

claude mcp add pdfops -- npx -y pdfops-mcp
# with a key:
claude mcp add pdfops -e PDFOPS_API_KEY=pdfops_live_… -- npx -y pdfops-mcp

Claude Desktop（claude_desktop_config.json）/ Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "pdfops": {
      "command": "npx",
      "args": ["-y", "pdfops-mcp"],
      "env": { "PDFOPS_API_KEY": "pdfops_live_…" }
    }
  }
}

VS Code（.vscode/mcp.json，注意 servers 键和 type）

{
  "servers": {
    "pdfops": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pdfops-mcp"],
      "env": { "PDFOPS_API_KEY": "pdfops_live_…" }
    }
  }
}

任何其他 stdio 客户端（Windsurf、Cline、Zed 或你自己的 Agent）：命令为 npx，参数为 -y pdfops-mcp。各客户端的操作指南和真实工具调用记录请见：pdfops.dev/mcp。

PDFOPS_API_KEY 为可选项——不提供密钥即可使用免密试用额度（每个 IP 每月 100 次请求）。在 pdfops.dev/pricing 填写一个字段即可获取免费密钥（每月 250 次，无需银行卡）。

工具

工具	功能
pdf_inspect	列出 PDF 的表单字段（名称、类型、选项、值），并提供可直接粘贴的填写模板。遇到不熟悉的 PDF 时，先调用此工具。
pdf_fill	填写 AcroForm 字段 → 写入已填写的 PDF。可选的 flatten 会将值烘焙进 PDF 并移除表单。
pdf_merge	按顺序合并至少 2 个 PDF → 写入合并结果。
pdf_invoice	结构化数据 → 完整的发票 PDF。结果具有确定性：相同输入会产生字节完全一致的输出。
pdfops_usage	检查已配置密钥的配额。

托管端点（无需安装）

PDFops 也会在 https://pdfops.dev/api/mcp（Streamable HTTP）上为你运行此服务。无需密钥即可使用（免密试用额度为每个 IP 每月 100 次调用）；通过 https://pdfops.dev/pricing#free-key 获取免费密钥即可提高额度：

claude mcp add --transport http pdfops https://pdfops.dev/api/mcp
# with a key:
claude mcp add --transport http pdfops https://pdfops.dev/api/mcp --header "Authorization: Bearer $PDFOPS_API_KEY"

来源必须是 https:// URL 或 data: URI，结果会直接内联返回。Cursor 和 VS Code 的配置方法见：https://pdfops.dev/mcp#remote。

远程运行（Smithery、Glama 托管服务、云 IDE 网关）

托管 MCP 运行时会在一台无法访问 Agent 文件路径的机器上执行此服务。配置无需更改——只需传入服务可以访问的来源，并省略 output_path：

• 输入（pdf_path、pdf_paths）：服务可获取的 https:// URL（每个 PDF ≤4 MB，每个请求 ≤4.5 MB——这是 API 的限制），或适用于小文件的 data:application/pdf;base64,… URI。
• 输出：省略 output_path 后，pdf_fill / pdf_merge / pdf_invoice 会以内嵌的 application/pdf 资源（pdfops://filled.pdf，…）返回 PDF，由客户端保存。设置 output_path 后，文件会写入服务运行所在的位置。

在本地运行时，绝对路径仍可像以前一样使用，也是推荐的方式——字节不会经过模型上下文。

提示词示例

• “~/forms/fw9.pdf 有哪些字段？” → pdf_inspect
• “为 Ada Lovelace 填写 ~/forms/fw9.pdf，地址为 12 Analytical Way, London；扁平化后保存为 ~/out/w9-ada.pdf” → pdf_inspect，然后使用 flatten: true 调用 pdf_fill
• “为 contractors.csv 的每一行填写一份入职表单，并保存到 ~/out/” → 调用一次 pdf_inspect，然后每行调用一次 pdf_fill
• “将 /out/w9-ada.pdf、/docs/nda.pdf 和 ~/docs/cover.pdf 合并为一个文件包，封面放在最前面” → pdf_merge
• “为 Globex 开具发票：3 天咨询服务，每天 $650，税率 8.5%，30 天后到期” → pdf_invoice
• “这个月我还剩多少次 PDFops 请求？” → pdfops_usage

Agent 工作流示例

“为 Ada Lovelace 填写 ~/docs/w9.pdf 中的 W-9 模板，并将其与 ~/docs/cover.pdf 合并”

1. pdf_inspect → 查找字段名称并获取填写模板
2. pdf_fill → 写入已填写的 W-9
3. pdf_merge → 写入合并后的文件包

链接

API 文档：pdfops.dev/docs · OpenAPI：pdfops.dev/openapi.json · 类型化客户端：pdfops-sdk · 问题咨询：[email protected]

隐私政策

此服务在你的计算机上运行，只会向 PDFops API（https://pdfops.dev）发送工具调用所需的内容：你指定的 PDF 字节、你提供的字段值，以及你设置的 API 密钥（如果有）。PDFops 会在内存中处理请求并返回结果；不会存储你的文档。为管理配额和提供服务，API 请求会记录使用情况元数据。完整政策见 https://pdfops.dev/privacy。问题咨询：[email protected]。

MIT © PDFops