用途
pdfops-mcp 是一个 MCP（Model Context Protocol）服务器，旨在为 AI 智能体提供确定性的 PDF 处理工具。它由 PDFops API 支持，使代理能够执行检查 AcroForm 字段、填充表单、合并 PDF 和生成发票等操作。
主要能力
- 检查（inspect）：查看 PDF 中的 AcroForm 字段，获取字段名称和填充模板。
- 填充（fill）：根据提供的字段值填充 PDF 表单，支持扁平化（flatten）输出。
- 合并（merge）：将多个 PDF 文件按指定顺序合并为一个文件。
- 生成发票（invoice）：根据客户、项目、金额、税率、到期日等信息生成发票 PDF。
- 用量查询（usage）：查询本月剩余的 PDFops 请求次数。
使用方式
本地代理
在本地运行代理时，工具操作基于文件路径。代理可以指定输入 PDF 路径和输出路径，PDF 字节不会进入模型上下文。例如：“填充 /tmp/form.pdf 并保存到 /tmp/out.pdf”，代理会收到一行确认信息。每个 PDF 输入也接受 https:// URL 或 data:application/pdf;base64,… URI。每次输出也可以内联返回而不写入文件。
配置
- Claude Desktop：在 claude_desktop_config.json 中配置。
- Cursor：在 .cursor/mcp.json 中配置。
- VS Code：在 .vscode/mcp.json 中配置，注意 servers 键和 type。
- 其他 stdio 客户端（Windsurf、Cline、Zed、自定义代理）：命令为 npx，参数为 -y pdfops-mcp。
托管端点（无需安装）
PDFops 也在 https://pdfops.dev/api/mcp 运行此服务器（Streamable HTTP）。需要 API 密钥，可在 https://pdfops.dev/pricing#free-key 免费获取。源必须是 https:// URL 或 data: URI，结果内联返回。Cursor 和 VS Code 的设置参见 https://pdfops.dev/mcp#remote。
远程运行（Smithery、Glama 托管、云 IDE 网关）
托管 MCP 运行时在代理的文件路径不存在的机器上执行此服务器。配置不变：传递服务器可访问的源并省略 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 会以内联方式返回 PDF 作为嵌入式 application/pdf 资源（如 pdfops://filled.pdf），由客户端保存。设置 output_path 时，文件写入服务器运行的位置。
在本地，绝对路径仍像以前一样工作，并且仍是推荐形式——字节不会进入模型上下文。
示例提示
- “~/forms/fw9.pdf 有哪些字段？” → pdf_inspect
- “为 Ada Lovelace, 12 Analytical Way, London 填充 ~/forms/fw9.pdf；扁平化保存为 ~/out/w9-ada.pdf” → pdf_inspect，然后 pdf_fill 带 flatten: true
- “为 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
示例代理流程
“为 Ada Lovelace 填充 ~/docs/w9.pdf 的 W-9 模板，并与 ~/docs/cover.pdf 合并”
- pdf_inspect → 发现字段名和填充模板
- pdf_fill → 写入填充后的 W-9
- pdf_merge → 写入合并后的包
适用场景
- 需要自动化处理 PDF 表单填充、合并和发票生成的 AI 代理工作流。
- 希望避免将 PDF 字节传入模型上下文的本地代理。
- 在托管运行时或云 IDE 中需要 PDF 工具但无法访问本地文件路径的场景。
限制
- 托管端点需要 API 密钥，源必须是 https:// URL 或 data: URI，结果内联返回。
- 远程运行时，输入 URL 的 PDF 大小限制为每个 PDF ≤4 MB，每个请求 ≤4.5 MB。
- 无密钥试用版每月每 IP 100 次请求；免费密钥每月 250 次请求。
- 服务器在您的机器上运行，仅向 PDFops API 发送工具调用所需的内容：您指向的 PDF 字节、您提供的字段值以及您的 API 密钥（如果设置了）。PDFops 在内存中处理请求并返回结果，不存储您的文档。API 请求会记录使用元数据以运行配额和服务。
其他信息
- API 文档：pdfops.dev/docs
- OpenAPI：pdfops.dev/openapi.json
- 类型化客户端：pdfops-sdk
- 问题咨询：hello@pdfops.dev
- 隐私政策：https://pdfops.dev/privacy