Pdfedit MCP

@niubai/pdfedit-mcp — edit existing PDFs from your agent

Five MCP tools over the PDF Edit API: replace, delete, redact, insert, form-fill, stamp or remove an image inside a PDF that already exists, keeping the original font, the original layout and everything you did not point at. Not "generate a new PDF that looks similar" — the same file, with the words you named changed, and a before/after picture of every change.

With PDFEDIT_BASE_URL unset the server talks to the hosted API at

https://api.niubai.vip; set it to point at another deployment.

Try it in 30 seconds, no key

Without PDFEDIT_API_KEY the server runs on the keyless free tier: 20 pages a day per IP, outputs watermarked TEST, local files included.

Claude Code

claude mcp add pdfedit -- npx -y @niubai/pdfedit-mcp

Cursor / VS Code / Claude Desktop — this server entry (or the buttons on the repository page):

{ "pdfedit": { "command": "npx", "args": ["-y", "@niubai/pdfedit-mcp"] } }

Then ask your agent: *"In ./contract.pdf replace 'Acme Ltd' with 'Acme GmbH' and redact the IBAN."* The edited PDF is written next to the original and a before/after picture of every change comes back. A free API key (200 pages a month, no watermark on ordinary documents) takes one email at https://api.niubai.vip.

Install

Claude Code — one line:

claude mcp add pdfedit -e PDFEDIT_API_KEY=sk_live_your_key -- npx -y @niubai/pdfedit-mcp

Cursor — the deeplink (Settings → MCP also takes the same JSON):

cursor://anysphere.cursor-deeplink/mcp/install?name=pdfedit&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBuaXViYWkvcGRmZWRpdC1tY3AiXSwiZW52Ijp7IlBERkVESVRfQVBJX0tFWSI6InNrX2xpdmVfeW91cl9rZXkifX0=

Claude Desktop — claude_desktop_config.json:

{

"mcpServers": { "pdfedit": { "command": "npx", "args": ["-y", "@niubai/pdfedit-mcp"], "env": { "PDFEDIT_API_KEY": "sk_live_your_key" } } } }

No key? Leave env out: the keyless free tier is 20 pages/day per IP, outputs watermarked TEST. Web clients that cannot run a local server (claude.ai) can add the hosted endpoint instead; it takes PDF URLs only.

Local files versus URLs

This package runs on your machine, so every tool's file argument takes an absolute (or `~`) local path — it uploads the file for you and writes the edited PDF back next to the input as .edited.pdf — or an https:// URL, or an f_… file id from an earlier call. The hosted Streamable-HTTP endpoint cannot read your disk and says so (*remote server cannot read local paths; pass a URL*). PDFs never travel as MCP content blobs either way; only up to three preview PNGs of the changed pages come back inline.

Tools

Every schema is generated from the gateway's OpenAPI document, so an edits[] entry here is exactly the one POST /v1/edit and the SDKs take — see src/tools.ts.

What it will refuse, and why

The engine would rather hand back "no" with a reason than a file that looks edited and is not. Two kinds of refusal.

Verification gates — the edit was attempted and rolled back

Every change is written, then checked, then kept or undone. A group that fails any gate is rolled back and reported in failed[]:

With options.atomic (the default) any single failure fails the whole request and no file is produced; options.strict does the same for an edit that simply did not match. An unmatched edit comes back with fuzzy suggestions ("did you mean *Acme, Inc.*?") rather than a silent no-op.

Known-unsupported — rejected up front as invalid_request

What the API refuses before touching the document:

• Right-to-left text (Arabic, Hebrew) in find. Everything after the matcher is left-to-right: lines are assembled left edge first and replacements are laid out rightwards, so RTL would be matched against a visually reversed line and written in the wrong direction with nothing downstream able to notice.
• `redact` on text that only exists as scanned pixels. The word *is* the image; covering it leaves it in the file, so the op's promise cannot be kept.
• `style` together with `fit: "reflow"`. A reflow re-sets the whole paragraph in the document's own face, so the matched phrase no longer has a run of its own to style.
• `fit: "reflow"` on `redact` or `form`.
• `options.preview: "pages"` (whole-page previews); "changes" and "none" work.
• Unknown ops.

Known limits — supported, with a caveat worth knowing

• A raster OCR write produces an image, not text. Where a scanned line has no underlying text to clone, the new words are drawn as pixels: correct on the page, verified by re-rendering, but not selectable or searchable afterwards.
• A redaction on a scan is verified by the text layer and the pixel scrub, not by recognising the output again.
• Text positioned relatively — matplotlib writes each tick relative to the previous one — can make an unrelated element move hundreds of points away. The engine sees that as collateral damage and rolls the change back; the page stays correct, the edit does not happen. One corpus file does this on purpose as a regression.
• Fonts. A replacement is set in the document's own font where the file embeds enough of it (any page's subset of that font counts), in a metric-compatible twin where it does not (Arial, Helvetica, Times New Roman, Courier New, Calibri, Cambria, Georgia, Segoe UI, Palatino, Book Antiqua, Bookman, Century Gothic, Avant Garde, New Century Schoolbook and Arial Narrow all have one: same widths, so the line ends where it did), and in a look-alike of the same class as a last resort. The result always says which (font_source, font_used), the summary spells out approx_font_used when the last resort was taken, and options.font.policy: "metric_only" refuses it outright, so "it looks slightly different" is a value you can read rather than a surprise.
• `flatten` on radio groups and comboboxes depends on the appearance the file carries; where it declines, the field is left live and flatten_skipped is warned instead of failing.
• Encrypted documents need the open password (password); edits are not attempted without it.

More

• Quick start — install per client, what to say to the agent, what comes back. The canonical usage doc; this README stays short on purpose.
• API reference — every field of edits[], options and the response.
• Examples — ten before/after pairs, each with the request that produced it.
• Repository — this server, the SDKs and the hosted endpoint's source.

MIT -- this server, the SDKs, the agent skill and the OpenAPI document. The hosted API itself is a proprietary service.