pdfops-mcp
Officialpdfops-mcp is an MCP server that provides deterministic PDF tools backed by the PDFops API, locally or on hosted runtimes.
Inspect PDF AcroForm fields, options, values, max lengths, XFA flag, and get a paste-ready fill template.
Fill PDF forms, optionally flatten values or open user-password PDFs.
Merge two or more PDFs in a specified order.
Generate complete invoice PDFs from structured data deterministically.
Edit PDFs by extracting, deleting, rotating, or splitting pages; adding watermarks or page numbers; unlocking/protecting encryption; and reading/writing metadata.
Accept PDF inputs as local paths,
https://URLs, or base64data:URIs, and write outputs to disk or return them inline.Check the configured PDFops API quota and remaining usage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pdfops-mcp fill ~/docs/w9.pdf for Ada Lovelace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpClaude 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.
Related MCP server: tooldash-mcp
Tools
Tool | What it does |
| List a PDF's form fields (names, types, options, values) + a paste-ready fill template. Call first on unfamiliar PDFs. |
| Fill AcroForm fields → write the filled PDF. Optional |
| Merge ≥2 PDFs in order → write the result. |
| Structured data → complete invoice PDF. Deterministic: same input, byte-identical output. |
| Keep only the listed pages, in the order given (also reorders and duplicates) → write the result. |
| Remove the listed pages, keep the rest in order → write the result. |
| Rotate pages clockwise by 90, 180, 270 or -90 degrees; all pages unless |
| Split into several PDFs by |
| Stamp a diagonal text watermark (opacity, size, colour, position, page selection). |
| Print page numbers from a |
| Save without encryption so print/copy restrictions are gone. Does not crack unknown passwords. |
| Encrypt with a user and/or owner password and a list of allowed permissions. |
| Read page count, per-page sizes and rotation, title/author/dates, encryption flag and form field count. |
| Write title, author, subject, creator and keywords. |
| Quota check for the configured key. |
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): anhttps://URL the server can fetch (≤4 MB per PDF, ≤4.5 MB per request — the API's limits), or adata:application/pdf;base64,…URI for small files.Outputs: omit
output_pathand the PDF-producing tools (pdf_fill,pdf_merge,pdf_invoice,pdf_rotate, …) return the PDF inline as an embeddedapplication/pdfresource (pdfops://filled.pdf, …) that the client saves. Withoutput_pathset, 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, thenpdf_fillwithflatten: true"Fill the onboarding form once per row of contractors.csv into ~/out/" → one
pdf_inspect, thenpdf_fillper 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, thenpdf_rotate"Split ~/docs/report.pdf into 10-page chunks in ~/out/" →
pdf_splitwithevery: 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"
pdf_inspect→ discovers field names + fill templatepdf_fill→ writes the filled W-9pdf_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
Available Tools
5 toolspdf_fillFill PDF formAIdempotentInspect
Fill AcroForm form fields in a PDF and save or return the result. Field names must exist in the PDF (use pdf_inspect first). All values are strings; checkboxes take "true"/"false"; dropdown/radio/optionlist values must be one of the field's options; text values must respect the field's maxLength from pdf_inspect. The source PDF is never modified. Returns the filled PDF written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. Encrypted PDFs are rejected with decrypt advice (common for government blanks with an empty user password), and a rejected fill writes no file at all.
Inputs: fields (required), pdf_path (required), flatten, output_path. Returns: bytes, output_path, resource_uri
pdf_inspectInspect PDF form fieldsARead-onlyIdempotentInspect
List a PDF's AcroForm form fields — names, types, options, current values, per-field maxLength where declared — plus a paste-ready fillTemplate object for pdf_fill and a hasXFA flag (hybrid AcroForm/XFA inputs lose their XFA layer when filled). A PDF with no fillable form returns count 0. Read-only: the PDF is fetched or read but never modified. Call this FIRST when filling an unfamiliar PDF, since pdf_fill rejects unknown field names and over-length values.
Inputs: pdf_path (required). Returns: count, fields, hasXFA, fillTemplate
pdf_invoiceGenerate invoice PDFAIdempotentInspect
Generate a complete, professionally laid-out invoice PDF from structured data — no template needed. Deterministic: the same input produces byte-identical output (safe to re-run). Note: without a paid PDFops key the output carries a small "Generated with pdfops.dev" footer line. Returns the invoice written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. Use this when you have invoice DATA and no document; if you already have an invoice PDF or a fillable template to populate, use pdf_fill instead.
Inputs: invoice (required), output_path. Returns: bytes, output_path, resource_uri
pdf_mergeMerge PDFsAIdempotentInspect
Merge two or more PDFs into one, in the order given, and save or return the result. Source files are read only and never modified; an existing file at output_path is overwritten. Returns the merged PDF written to output_path, or inline as an application/pdf resource when output_path is omitted. This tool only concatenates whole documents: it does not reorder, rotate or delete pages within them, and it does not fill forms — use pdf_fill for a fillable form and pdf_invoice to build a document from data. An unreadable or rejected input fails with an error and writes no file, so a partial merge is never left behind.
Inputs: pdf_paths (required), output_path. Returns: bytes, output_path, resource_uri
pdfops_usageCheck PDFops quotaARead-onlyIdempotentInspect
Check the current PDFops API quota for the configured key: tier, limit, used, remaining, the billing period, and the reset timestamp. Read-only and safe to call before a batch to confirm there is headroom. Requires PDFOPS_API_KEY.
Inputs: no named parameters. Returns: tier, used, limit, period, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: inspecting form fields, filling forms, merging documents, generating invoices, and checking API usage. The descriptions explicitly cross-reference when to use each tool, so an agent is unlikely to select the wrong one.
Most tools follow a clear pdf_<verb> pattern like pdf_inspect, pdf_fill, and pdf_merge. pdf_invoice is a noun-style exception and pdfops_usage breaks the prefix pattern, but the names remain readable and generally predictable.
Five tools is a well-scoped size for a focused PDF utility server. Each tool covers a distinct non-redundant operation, and none feel unnecessary or missing for the stated workflow.
The inspect-then-fill form workflow is well covered, and merge plus invoice generation provide useful end-to-end PDF creation paths without dead ends. Common PDF operations like splitting or rotating pages are absent, but the set appears intentionally scoped to form filling, merging, and invoice generation.
Maintenance
Related MCP Connectors
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
Generate and read PDFs for AI agents: a generate_pdf and a read_pdf tool, priced per document.
PDF tools for AI agents: validate, extract, merge, split, compress, OCR, sign and redact.
Persistent memory, inline redaction, per-agent access, and code localization for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to perform comprehensive PDF operations locally, including compression, text extraction, PII redaction, page organization, splitting, merging, watermarking, creation, and form filling, all without cloud uploads.21 npm-
- AlicenseAqualityDmaintenanceEnables AI agents to inspect PDFs, merge or extract pages, and clean text entirely offline through the Model Context Protocol, with no uploads, API keys, or network calls.460 npmMIT
- AlicenseBqualityBmaintenanceEnables AI agents to perform local-first PDF processing entirely on-device, including OCR write-back to make scans searchable, unlocking and re-encrypting PDFs, splitting/merging/rotating pages, and compressing files, with no cloud calls or file uploads.251MIT
- AlicenseAqualityBmaintenanceEnables AI agents to inspect and work with PDF files entirely on the local machine, covering page counts, metadata, layout, encryption permissions, scan-vs-text detection, and page rendering. Generated results land in a temporary workspace as short artifact ids that can be chained between tools and exported to real folders on request.1256 PyPI1Apache 2.0