Enables AI agents to inspect, fill, merge, split, and edit PDF documents using deterministic tools.
Also known as pdfops/pdfops-mcp
- Stars
- 0
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- 0.4.5
- Last commit
- Nov 12, 2026
- License
- MIT
What is pdfops MCP?
pdfops enables AI agents to inspect, fill, merge, split, and edit PDF documents using deterministic tools. It exposes 15 tools, such as pdf_inspect, pdf_fill, pdf_merge.
Summary generated from the project's README
About pdfops MCP server
Automating document workflows by manipulating PDF files through an AI agent is what pdfops-mcp enables. This server provides deterministic tools for inspecting AcroForm fields, filling forms, merging multiple documents, and generating invoices from structured data. It also handles advanced editing tasks like splitting, rotating, watermarking, and managing page numbers or metadata.
Developers can run this server locally using npx with clients like Claude Desktop, Cursor, or VS Code, or connect to a hosted endpoint via HTTP. When running locally, the agent operates on file paths to ensure PDF bytes never enter the model context. For remote environments where local paths are unavailable, the server accepts https URLs or base64 URIs and returns results inline. A PDFOPS_API_KEY is required for higher usage limits, though a keyless trial allows 100 requests per month per IP.
What you can do with it
- 1Automated form completionAn agent can identify form fields in a template and fill them with specific user data.
- 2Document assembly and mergingCombine several separate PDF files into a single organized document packet.
- 3Invoice generation from dataCreate a byte-identical invoice PDF using structured input like service duration and tax rates.
- 4Page manipulation and organizationExtract specific pages, delete unwanted ones, or split a large report into smaller chunks.
Written from the project's README. Every use case is checked against a quote from it.
How to install pdfops MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall pdfops MCP in Claude Code
$ claude mcp add pdfops-mcp -- npx -y pdfops-mcpInstall pdfops MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pdfops-mcp": {
"command": "npx",
"args": [
"-y",
"pdfops-mcp"
]
}
}
}Install pdfops MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pdfops-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pdfops-mcp"
]
}
}
}Install pdfops MCP in VS Code CLI
$ code --add-mcp '{"name":"pdfops-mcp","type":"stdio","command":"npx","args":["-y","pdfops-mcp"]}'Install pdfops MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pdfops-mcp": {
"command": "npx",
"args": [
"-y",
"pdfops-mcp"
]
}
}
}Install pdfops MCP in Codex
$ codex mcp add pdfops-mcp -- npx -y pdfops-mcpInstall pdfops MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pdfops-mcp] command = "npx" args = ["-y", "pdfops-mcp"]
Install pdfops MCP in Gemini CLI
$ gemini mcp add -s user pdfops-mcp npx -- -y pdfops-mcpInstall pdfops MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pdfops-mcp": {
"command": "npx",
"args": [
"-y",
"pdfops-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pdfops-mcp 0.4.5 in an isolated container with no network and no keys. It answered and listed 15 tools.
pdfops MCP tools 15
Read from the server with tools/listpdf_inspectRead-onlyList 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.
pdf_fillActionFill 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. Owner-locked PDFs (empty user password, common for government blanks) fill without a password; a user-password PDF needs the password parameter, otherwise it is rejected with encrypted_pdf. A rejected fill writes no file at all.
pdf_mergeActionMerge 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.
pdf_invoiceActionGenerate 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.
pdfops_usageRead-onlyCheck 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.
pdf_extract_pagesActionKeep only the listed pages of a PDF, in the order given, and return them as a new PDF. Because order follows the spec, it also reorders pages ("3,1,2") and can duplicate them. Use this to pull a section out of a document; use pdf_delete_pages to remove pages instead, pdf_split for several output files, and pdf_merge to join documents. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified. Fails with invalid_pages if a page is out of range.
pdf_delete_pagesActionRemove the listed pages from a PDF and return the remaining pages in their original order. Use this to drop a cover, blank or sensitive pages; use pdf_extract_pages when it is easier to name the pages to keep. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified. Deleting every page fails with no_pages_left.
pdf_rotateActionRotate pages of a PDF clockwise by 90, 180 or 270 degrees (or -90). Rotation adds to each page's existing rotation. Omit pages to rotate every page. Use this to fix sideways scans. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
pdf_splitActionSplit one PDF into several PDFs, either by explicit ranges (each comma group becomes one part: "1-2,3-5" gives two parts) or into fixed-size chunks (every=2 on 5 pages gives 1-2, 3-4, 5). Give exactly one of ranges or every. With output_dir the parts are written there as part-1.pdf, part-2.pdf, …; otherwise each part comes back inline as an application/pdf resource. Either way you also get a structured parts list (pages, page_count, bytes, and output_path or resource_uri). Existing part-N.pdf files with those names are overwritten, and part-N.pdf files from earlier runs in that directory are left as they are; the source is never modified. Limited to 100 parts and about 4 MB of total output; use pdf_extract_pages for a single range.
pdf_watermarkActionStamp a diagonal text watermark on pages of a PDF (default: centered, 45 degrees, grey, 15% opacity). Text is upright and centered for any page size or existing page rotation. Standard Helvetica only: characters outside WinAnsi (e.g. CJK, emoji) fail with unsupported_characters. Use this for DRAFT / CONFIDENTIAL stamps; use pdf_page_numbers for numbering. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
pdf_page_numbersActionPrint page numbers on a PDF using a format template with {n} (page number) and {total} (page count), e.g. "Page {n} of {total}". Default is "{n} / {total}" at bottom-center, 10 pt. Numbers sit upright for any page size or rotation. Standard Helvetica only (WinAnsi characters). Page i always shows start+i-1 even when pages selects only some pages. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
pdf_unlockActionSave a PDF without encryption so print/copy/modify restrictions are gone. Works for owner-locked files (empty user password) with no password, and for user-password files when you pass the password. It does NOT crack unknown passwords: a wrong or missing user password fails with encrypted_pdf. A PDF that was not encrypted is returned re-saved, with note "not-encrypted". Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
Show all 15 toolsShow fewer tools
pdf_protectActionEncrypt a PDF with a password. user_password is required to open the result; owner_password lifts the permission restrictions. Give at least one (each 1 to 32 Latin-1 chars). permissions lists what stays ALLOWED from print, copy, modify, annotate, fill-forms (default all, except modify when an owner password is set; an empty list allows none). Restrictions only bind viewers when an owner password is set. Not byte-deterministic (random salts). Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
pdf_metadataRead-onlyRead a PDF's document info: page_count, per-page width/height (points) and rotation, title, author, subject, keywords, creator, producer, creation_date, modification_date (ISO 8601, null when absent), whether it was encrypted, and has_form / form_field_count. Call this to learn a document's size and shape before splitting, rotating or filling. Read-only: the PDF is fetched or read but never modified.
pdf_set_metadataActionWrite document info fields (title, author, subject, creator, keywords) into a PDF. Give at least one; an empty string sets an empty value. Unicode is fine. Keywords may be a list or a comma-separated string. The output is saved unencrypted. Use pdf_metadata to read the current values. Returns the result written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. The source is never modified.
Configuration
PDFOPS_API_KEY
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubpdfops-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
| Tool | What it does |
|---|---|
pdf_inspect |
List a PDF's form fields (names, types, options, values) + a paste-ready fill template. Call first on unfamiliar PDFs. |
pdf_fill |
Fill AcroForm fields → write the filled PDF. Optional flatten bakes values in and drops the form; optional password opens a user-password PDF. |
pdf_merge |
Merge ≥2 PDFs in order → write the result. |
pdf_invoice |
Structured data → complete invoice PDF. Deterministic: same input, byte-identical output. |
pdf_extract_pages |
Keep only the listed pages, in the order given (also reorders and duplicates) → write the result. |
pdf_delete_pages |
Remove the listed pages, keep the rest in order → write the result. |
pdf_rotate |
Rotate pages clockwise by 90, 180, 270 or -90 degrees; all pages unless pages is given. |
pdf_split |
Split into several PDFs by ranges or fixed-size every chunks → part-1.pdf, part-2.pdf, … in output_dir, or inline. |
pdf_watermark |
Stamp a diagonal text watermark (opacity, size, colour, position, page selection). |
pdf_page_numbers |
Print page numbers from a {n} / {total} template, with position, start number and margin. |
pdf_unlock |
Save without encryption so print/copy restrictions are gone. Does not crack unknown passwords. |
pdf_protect |
Encrypt with a user and/or owner password and a list of allowed permissions. |
pdf_metadata |
Read page count, per-page sizes and rotation, title/author/dates, encryption flag and form field count. |
pdf_set_metadata |
Write title, author, subject, creator and keywords. |
pdfops_usage |
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
pdfops MCP questions
How do I add pdfops MCP to Claude Code?
Run claude mcp add pdfops-mcp -- npx -y pdfops-mcp in your terminal. Add --scope user to make it available in every project.
How do I add pdfops MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does pdfops MCP provide?
It exposes 15 tools, including pdf_inspect, pdf_fill, pdf_merge, pdf_invoice, pdfops_usage.
Does the server require Chromium or native dependencies?
No, the server requires no Chromium or native dependencies to run.
How does the server handle file privacy and security?
The server processes requests in memory and does not store your documents.
Can I use the server without an API key?
Yes, you can use a keyless trial which allows 100 requests per IP per month.
Is the invoice generation deterministic?
Yes, the invoice tool provides byte-identical output for the same input.