# pdfops MCP server

> Enables AI agents to inspect, fill, merge, split, and edit PDF documents using deterministic tools.

- Repository: https://github.com/pdfops/pdfops-mcp
- Page: https://hostedmcp.org/servers/pdfops/pdfops-mcp
- Transport: stdio, remote
- Stars: 0
- License: MIT
- Latest version: 0.4.5

## Install

### Claude Code

```sh
claude mcp add pdfops-mcp -- npx -y pdfops-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "pdfops-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pdfops-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pdfops-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "pdfops-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pdfops-mcp","type":"stdio","command":"npx","args":["-y","pdfops-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "pdfops-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pdfops-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add pdfops-mcp -- npx -y pdfops-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pdfops-mcp]
command = "npx"
args = ["-y", "pdfops-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user pdfops-mcp npx -- -y pdfops-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "pdfops-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pdfops-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PDFOPS_API_KEY` | no | no |  |

## Tools (15)

- `pdf_inspect`: 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. (read-only)
- `pdf_fill`: 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. 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_merge`: 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.
- `pdf_invoice`: 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.
- `pdfops_usage`: 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. (read-only)
- `pdf_extract_pages`: Keep 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_pages`: Remove 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_rotate`: Rotate 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_split`: Split 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_watermark`: Stamp 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_numbers`: Print 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_unlock`: Save 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.
- `pdf_protect`: Encrypt 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_metadata`: Read 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. (read-only)
- `pdf_set_metadata`: Write 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.

## FAQ

### 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.
