Purpose
pdfops-mcp is an MCP (Model Context Protocol) server designed to provide AI agents with deterministic PDF processing tools. It is powered by the PDFops API, enabling agents to perform operations such as inspecting AcroForm fields, filling forms, merging PDFs, and generating invoices.
Main Capabilities
- inspect: View AcroForm fields in a PDF, obtain field names and filling templates.
- fill: Fill a PDF form based on the provided field values, with support for flattened output.
- merge: Merge multiple PDF files into one file in the specified order.
- invoice: Generate an invoice PDF based on information such as customer, items, amount, tax rate, and due date.
- usage: Query the number of remaining PDFops requests for this month.
Usage
Local Agent
When running the agent locally, tool operations are based on file paths. The agent can specify the input PDF path and output path, and PDF bytes do not enter the model context. For example: "Fill /tmp/form.pdf and save to /tmp/out.pdf", and the agent receives a one-line confirmation message. Each PDF input also accepts an https:// URL or a data:application/pdf;base64,... URI. Each output can also be returned inline without writing to a file.
Configuration
- Claude Desktop: Configure in claude_desktop_config.json.
- Cursor: Configure in .cursor/mcp.json.
- VS Code: Configure in .vscode/mcp.json, noting the servers key and type.
- Other stdio clients (Windsurf, Cline, Zed, custom agents): The command is npx, and the argument is -y pdfops-mcp.
Hosted Endpoint (No Installation Required)
PDFops also runs this server at https://pdfops.dev/api/mcp (Streamable HTTP). An API key is required and can be obtained for free at https://pdfops.dev/pricing#free-key . The source must be an https:// URL or a data: URI, and results are returned inline. For Cursor and VS Code setup, see https://pdfops.dev/mcp#remote。
Remote Running (Smithery, Glama Hosting, Cloud IDE Gateway)
Hosted MCP runtimes execute this server on machines where the agent's file paths do not exist. The configuration is unchanged: pass a source accessible to the server and omit output_path.
- Input (pdf_path, pdf_paths): An https:// URL that the server can fetch (each PDF ≤4 MB, each request ≤4.5 MB, which is the API's limit), or a data:application/pdf;base64,... URI for small files.
- Output: Omit output_path, and pdf_fill / pdf_merge / pdf_invoice will return the PDF inline as an embedded application/pdf resource (such as pdfops://filled.pdf), which the client saves. When output_path is set, the file is written to the location where the server runs.
Locally, absolute paths still work as before and remain the recommended form - bytes do not enter 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 flattened as ~/out/w9-ada.pdf" → pdf_inspect, then pdf_fill with flatten: true
- "Fill the onboarding form to ~/out/ for each row of contractors.csv" → one pdf_inspect, then one pdf_fill per row
- "Merge ~/out/w9-ada.pdf, ~/docs/nda.pdf, and ~/docs/cover.pdf into one package, with the cover first" → pdf_merge
- "Issue an invoice to Globex for 3 days of consulting at $650, 8.5% tax, due in 30 days" → pdf_invoice
- "How many PDFops requests are left this month?" → pdfops_usage
Example Agent Flow
"For Ada Lovelace Fill the W-9 template at ~/docs/w9.pdf and merge it with ~/docs/cover.pdf"
- pdf_inspect → discover field names and fill template
- pdf_fill → write the filled W-9
- pdf_merge → write the merged package
Use cases
- AI agent workflows that need to automate PDF form filling, merging, and invoice generation.
- Local agents that want to avoid passing PDF bytes into the model context.
- Scenarios in hosted runtimes or cloud IDEs where PDF tools are needed but local file paths are inaccessible.
Limitations
- Hosted endpoints require an API key, the source must be an https:// URL or a data: URI, and results are returned inline.
- For remote runtimes, the PDF size limit for input URLs is ≤4 MB per PDF and ≤4.5 MB per request.
- The keyless trial allows 100 requests per IP per month; a free key allows 250 requests per month.
- The server runs on your machine and sends only what is needed for tool calls to the PDFops API: the PDF bytes you point to, the field values you provide, and your API key (if set). PDFops processes requests in memory and returns results without storing your documents. API requests log usage metadata to run quotas and the service.
Additional information
- API documentation: pdfops.dev/docs
- OpenAPI: pdfops.dev/openapi.json
- Typed client: pdfops-sdk
- Questions: hello@pdfops.dev
- Privacy policy:https://pdfops.dev/privacy