Pdfops MCP README

pdfops-mcp

MCP server that gives AI agents deterministic PDF tools, backed by the PDFops API: inspect AcroForm fields, fill forms, merge PDFs, generate invoices, and edit PDFs (extract, delete, rotate and split pages, watermark, page numbers, unlock, protect, metadata) — no Chromium, no native deps, nothing to host.

Beside a local agent, tools operate on file paths, so PDF bytes never transit the model context: your agent says "fill /tmp/form.pdf and save to /tmp/out.pdf" and gets a one-line confirmation back. Every PDF input also accepts an https:// URL or a data:application/pdf;base64,… URI, and every output can be returned inline instead of written — which is what makes the server work on hosted runtimes (see below).

Install

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, note the servers key and type)

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

Any other stdio client (Windsurf, Cline, Zed, your own agent): command npx, args -y pdfops-mcp. Per-client walkthrough and a real tool-call transcript: pdfops.dev/mcp.

PDFOPS_API_KEY is optional — without it you get the keyless trial (100 requests/IP/month). A free key (250/month, no card) takes one field at pdfops.dev/pricing.

File access is confined. The server reads and writes only .pdf files inside PDFOPS_ROOT, which defaults to the directory the client starts it in (your home directory if that is /). Set it to the folder(s) holding your PDFs, separated by : (; on Windows), e.g. -e PDFOPS_ROOT=$HOME/Documents/forms. Inputs must start with a %PDF header, symlinks are resolved before the check, and URLs must be public https:// addresses (private, loopback and cloud-metadata hosts are refused on every redirect hop). Since 0.4.2.

Tools

Hosted endpoint (no install)

PDFops also runs this server for you at https://pdfops.dev/api/mcp (Streamable HTTP). It works without a key (keyless trial cap of 100 calls/IP/month); a free key from https://pdfops.dev/pricing#free-key raises the cap:

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"

Sources must be https:// URLs or data: URIs, and results come back inline. Setup for Cursor and VS Code: https://pdfops.dev/mcp#remote.

Running remotely (Smithery, Glama hosted, cloud IDE gateways)

A hosted MCP runtime executes this server on a machine where your agent's file paths do not exist. Nothing changes in the config — pass sources the server can reach and skip output_path:

• Inputs (pdf_path, pdf_paths): an https:// URL the server can fetch (≤4 MB per PDF, ≤4.5 MB per request — the API's limits), or a data:application/pdf;base64,… URI for small files.
• Outputs: omit output_path and the PDF-producing tools (pdf_fill, pdf_merge, pdf_invoice, pdf_rotate, …) return the PDF inline as an embedded application/pdf resource (pdfops://filled.pdf, …) that the client saves. With output_path set, the file is written where the server runs.

Locally, absolute paths keep working exactly as before and remain the recommended form — bytes stay off the model context.

Example prompts

• "What fields does ~/forms/fw9.pdf have?" → pdf_inspect
• "Fill ~/forms/fw9.pdf for Ada Lovelace, 12 Analytical Way, London; save it flattened as ~/out/w9-ada.pdf" → pdf_inspect, then pdf_fill with flatten: true
• "Fill the onboarding form once per row of contractors.csv into ~/out/" → one pdf_inspect, then pdf_fill per row
• "Merge ~/out/w9-ada.pdf, ~/docs/nda.pdf and ~/docs/cover.pdf into one packet, cover first" → pdf_merge
• "Invoice Globex for 3 days of consulting at $650, 8.5% tax, due in 30 days" → pdf_invoice
• "Drop pages 1-2 of ~/docs/scan.pdf and rotate the rest 90 degrees" → pdf_delete_pages, then pdf_rotate
• "Split ~/docs/report.pdf into 10-page chunks in ~/out/" → pdf_split with every: 10, output_dir
• "How many PDFops requests do I have left this month?" → pdfops_usage

Example agent flow

"Fill the W-9 template at ~/docs/w9.pdf for Ada Lovelace and merge it with ~/docs/cover.pdf"

1. pdf_inspect → discovers field names + fill template
2. pdf_fill → writes the filled W-9
3. pdf_merge → writes the combined packet

Links

API docs: pdfops.dev/docs · OpenAPI: pdfops.dev/openapi.json · Typed client: pdfops-sdk · Questions: hello@pdfops.dev

Privacy Policy

This server runs on your machine and sends only what a tool call needs to the PDFops API (https://pdfops.dev): the PDF bytes you point it at, the field values you supply, and your API key if you set one. PDFops processes the request in memory and returns the result; it does not store your documents. API requests are logged with usage metadata to run quotas and the service. The full policy is at https://pdfops.dev/privacy. Questions: hello@pdfops.dev.

MIT © PDFops