{ "markdown": "# mcp-pdf\n\n\n\n**MCP server for PDF tools that merge, split, stamp and read PDF files; merges and splits pages on your own machine.** Merge, split, stamp and read PDFs, pure JavaScript.\n\nWorks with Claude Desktop, Claude Code, Cursor and any Model Context Protocol client. Runs on your own machine, or hosted with no install.\n\n## Install\n\n**Hosted, nothing to install.** Get a token from (the connect page) or (the same token as JSON); a free anonymous one is issued on the spot and a Pro key works the same way. Then point an MCP client at `https://mcp.zovo.one/mcp/pdf` over streamable-http and send the token as `Authorization: Bearer `.\n\nIf your client cannot set headers, put the token in the path instead: `https://mcp.zovo.one/mcp/pdf/t/`. Both forms work. The bare URL with no token answers 401 on `tools/call`, so the token is not optional.\n\n**Claude Desktop, one click.** Download `pdf.mcpb` from the [latest release](https://github.com/theluckystrike/mcp-servers/releases/latest) and double-click it.\n\n**From source.** The mirror is self-contained: every `@theluckystrike/*` dependency is vendored, so a fresh clone builds with no extra setup.\n\n```sh\ngit clone https://github.com/theluckystrike/mcp-pdf.git\ncd mcp-pdf\nnpm install && npm run build\n```\n\nThen point your client at the built entry point:\n\n```json\n{\n \"mcpServers\": {\n \"pdf\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-pdf/dist/index.js\"]\n }\n }\n}\n```\n\n> `@theluckystrike/mcp-pdf` is **not published on npm yet**, so an `npx -y @theluckystrike/mcp-pdf` command will fail. The three paths above are the working ones and each is exercised by CI.\n\n![pdf demo](https://raw.githubusercontent.com/theluckystrike/mcp-servers/main/assets/demo-pdf.gif)\n\nRead-only mirror of [mcp-servers/servers/pdf](https://github.com/theluckystrike/mcp-servers/tree/main/servers/pdf). See [MIRROR.md](MIRROR.md).\n\n\n\nSay \"stamp PAID on that invoice and save a copy\" or \"pull pages 2 to 6 out of this scan and merge them with the contract\" and it happens, on your machine, in a second. This MCP server does the small PDF jobs that otherwise send you to a web uploader: merge, split by page range, extract or reorder pages, rotate a sideways scan, stamp `PAID` or `DRAFT` or any text you like, put your business name and VAT id in the footer, count pages across a folder of files, and read a PDF's text back as text. No upload, no account, no native dependency, no office install.\n\n\n**The PDF chores of a freelance business, done from chat instead of from a browser tab you do not trust with an invoice.**\n\n## 60-second install\n\nnpm publish for `@theluckystrike/mcp-pdf` is pending. Until then, the `.mcpb` one-click bundle or a clone+build\nis the working path -- both are verified below.\n\n**One-click (.mcpb):** download `pdf.mcpb` from the latest release and double-click it in Claude Desktop:\nhttps://github.com/theluckystrike/mcp-servers/releases/latest\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"pdf\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@theluckystrike/mcp-pdf\"]\n }\n }\n}\n```\n\n**Claude Code:**\n\n```sh\nclaude mcp add pdf -- npx -y @theluckystrike/mcp-pdf\n```\n\n**Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"pdf\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@theluckystrike/mcp-pdf\"]\n }\n }\n}\n```\n\nThe `npx` form above starts working the moment the package is published. Until then, use the .mcpb bundle above, or\nbuild from source with exactly these three commands:\n\n```sh\ngit clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers\nnpm install\nnpm run build -w packages/mcp-license -w servers/pdf\n```\n\nThen point your client's `command` at `node` with one arg: the absolute path to `servers/pdf/dist/index.js`.\n\nTo run in Pro mode set `MCP_LICENSE_KEY` in the same config block, or call `license_activate` once with your key.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `pdf_info` | Page count, every page's size in points and millimetres, the paper name (A4, Letter, custom), the rotation already on each page, the metadata (title, author, producer, dates) and whether the file is encrypted |\n| `pdf_count` | Page count per file plus the total, for any number of PDFs. A file it cannot read is reported per file; the rest still count |\n| `pdf_merge` | Join PDFs into one, in the order given. Page sizes are kept as they are, and a merged file with mixed sizes says so |\n| `pdf_split` | One new file per range. `\"1-3,5,7-\"` gives pages 1-3, page 5, and page 7 to the end. `out_path_pattern` takes `{n}`, `{range}` and `{name}` |\n| `pdf_pages` | Extract selected pages into one new PDF, in the order you write them. `\"5,1,1\"` puts page 5 first and page 1 in twice |\n| `pdf_rotate` | Turn pages by a multiple of 90 degrees, added to the rotation the page already had, which is what a sideways scan needs |\n| `pdf_stamp` | Draw text on the pages: `PAID` and `DRAFT` presets, or any text, colour, position, opacity and size. Centre stamps go on the 45-degree diagonal |\n| `pdf_watermark_business` | Your business name and VAT id in the footer of every page, from the shared profile [mcp-invoice](../invoice) and [mcp-docx](../docx) write |\n| `pdf_text` | Best-effort text extraction from the page content streams. See the honest caveats below |\n| `pdf_reorder` | Write a new PDF with the pages in a new order. The order must name every page exactly once, so nothing is dropped by accident |\n| `license_status` | Show free or Pro mode |\n| `license_activate` | Activate a Pro key (verified offline) |\n\nResource: `pdf://recent` returns the last 25 operations, newest first, with the inputs, the files written and when.\nPrompt: `mark_invoice_paid` chains [mcp-invoice](../invoice)'s `invoice_get` into `pdf_stamp PAID` and saves the stamped copy beside the original.\n\n## What you can say\n\n| You say | Tool |\n| --- | --- |\n| \"Mark invoice INV-2026-0007 as paid.\" | `mark_invoice_paid` prompt, then `pdf_stamp` |\n| \"Stamp DRAFT across this contract before I send it.\" | `pdf_stamp` |\n| \"Join these three PDFs into one file.\" | `pdf_merge` |\n| \"Split the scan: pages 1-3 are the invoice, 4 onwards is the receipt.\" | `pdf_split` |\n| \"Pull pages 2 to 6 out of this and save them separately.\" | `pdf_pages` |\n| \"This scan is sideways, turn it.\" | `pdf_rotate` |\n| \"How many pages are in all of these?\" | `pdf_count` |\n| \"What does page 1 of this PDF say?\" | `pdf_text` |\n| \"Put my company name and VAT number in the footer.\" | `pdf_watermark_business` |\n| \"Move the cover page to the front.\" | `pdf_reorder` |\n\n## Worked example\n\n```\nYou: Stamp PAID on ~/invoices/INV-2026-0007.pdf and save a copy.\n\n pdf_stamp {\n path: \"~/invoices/INV-2026-0007.pdf\",\n text: \"PAID\",\n position: \"center\",\n out_path: \"~/invoices/INV-2026-0007-paid.pdf\"\n }\n -> Stamped \"PAID\" on 1 page\n -> ~/invoices/INV-2026-0007-paid.pdf, 0.9 MB\n```\n\nThe stamp is drawn text, not a flattened image: it can be selected and searched, it is drawn on the 45-degree\ndiagonal in the preset green, and the original file is byte-for-byte unchanged.\n\n## Free vs Pro\n\n| | Free | Pro |\n| --- | --- | --- |\n| `pdf_info`, `pdf_count`, `pdf_text` | Unlimited | Unlimited |\n| `pdf_merge` | Up to 5 files per call | Any number of files |\n| `pdf_split`, `pdf_pages`, `pdf_rotate` | Files up to 30 pages | Any length |\n| `pdf_stamp` | The `PAID` and `DRAFT` presets in their preset colours | Any text, any colour, any size |\n| `pdf_watermark_business` | - | Your business name and VAT id in the footer |\n| `pdf_reorder` | - | Yes |\n\nA tier limit is an answer, not an error, and nothing is written when one refuses a call.\n\nPro is a one-time $19, or $39 for every server in the collection, lifetime.\n\n**Get Pro: https://mcp.zovo.one/buy/pdf**\n\n## `pdf_text` is best effort, and here is exactly what that means\n\nA PDF does not store text. It stores drawing operators, and the text you see is bytes handed to a font. This server\ndecompresses each page's FlateDecode content stream with `node:zlib` and reads the four text-showing operators --\n`Tj`, `TJ`, `'` and `\"` -- plus the positioning operators that end a line. That is a parser written here, in about\ntwo hundred lines, with no `pdfjs` and no native module, and it has three real limits the tool states in its own\nanswer every time:\n\n- **A scan has no text.** An image-only page carries no text operators, so nothing comes back. There is no OCR here\n and there will not be one; the answer says the page is probably a scan rather than returning an empty string with\n no explanation.\n- **A custom or CID encoding returns glyph indices, not letters.** Subset-embedded and CJK fonts map bytes to glyph\n numbers through a table this parser does not read. When the output has no readable characters, the answer says the\n font is the reason.\n- **Reading order is drawing order.** There is no column detection and no layout reconstruction. Word spaces are\n recovered from the large negative kerns a `TJ` array uses for them, so a PDF that positions every word separately\n can come back with words run together.\n\nPDFs written by word processors, invoicing tools and report generators -- everything with a standard or fully\nembedded font -- read back cleanly. Anything else tells you why it did not.\n\n## Encrypted PDFs are refused, not guessed\n\n`pdf-lib` cannot decrypt, and loading an encrypted file while ignoring the encryption produces pages of garbage that\nwould be written straight into the output. So a file whose trailer names an `/Encrypt` dictionary is refused by every\ntool that writes, with the reason and the fix in the message: open it in a reader with the password, export or print\nto a new PDF, and use that file. `pdf_info` still answers, with `encrypted: true`, because reporting is its whole job,\nand `pdf_count` reports it as one unreadable file while still counting the rest.\n\n## Existing files are never overwritten, and inputs are never modified\n\nEvery tool writes a new file and leaves its inputs byte-for-byte alone -- there is no in-place mode, on purpose.\nAn `out_path` that already exists is refused:\n\n```\nError: /path/merged.pdf already exists and nothing was written.\nPass overwrite: true to replace it, or give a different out_path.\n```\n\nThe path is reserved with an exclusive create, not an existence check, so two processes writing the same `out_path`\nat the same time cannot clobber each other: one wins, the other is refused and writes nothing. `pdf_split` reserves\nevery one of its output paths before it writes any of them, so a collision on part 3 does not leave parts 1 and 2\nbehind as a half-done split -- and the reservations are released, so nothing empty is left on disk either.\n\nPass `overwrite: true` when replacing the file is what you want.\n\n`overwrite: true` still does not let an output be an input. Writing the result of an operation back over one of its\nown sources destroys that source -- the pages are already in memory and get written over the file they came from,\nwhich takes a three-page file to the one page you extracted -- and every later read of that path is then quietly\nwrong. So an `out_path` that resolves to (or shares an inode with) any input of the same call is refused before any\nwork happens:\n\n```\nError: out_path /path/scan.pdf is also an input of this operation, so writing it would destroy the source.\nNothing was written. Write beside it instead - /path/scan-out.pdf - and, if the result really is meant to\ntake the original's place, rename it yourself once you have checked it.\n```\n\n## Limits\n\n- Inputs over 100 MB are refused: rewriting a PDF needs several times its size in memory.\n- A file that does not start with `%PDF-` is refused before anything is read.\n- Rotation is recorded as page metadata, in multiples of 90 degrees, which is all the format has. Nothing is redrawn.\n- Stamp text goes through a built-in PDF font, which carries WinAnsi and its 256 code points. A character outside it\n is transliterated where it has an obvious Latin body -- Polish `OPŁACONE` stamps as `OPLACONE`, and the answer says\n so and prints what was actually drawn -- and removed and counted where it does not, so there is no CJK stamp. A\n newline is a word separator, never a deletion.\n- `font_size` must be between 1 and 1600 points. A stamp too long to fit even at the smallest size this server will\n use is still drawn, and the answer says how far past the edge it runs, so you can shorten it.\n- `pdf_text` caps one answer at 200,000 characters and names the `pages` argument that continues from where it\n stopped. Nothing is missing from the file; the cut is in the answer, not the read.\n- No page numbering, no signatures, no redaction, no compression. This server does the page-level jobs; it is not a\n PDF editor. It does not *write* PDF/A: `pdf_info` reports a file's own `pdfa_claim`, and every tool that writes\n says plainly that its output no longer holds that claim.\n- Forms are read, not filled: `pdf_text` prints the AcroForm field values, which live in the fields rather than in\n the page content stream and are therefore not part of the page text.\n- No OCR. See the `pdf_text` section.\n\n## How it stores data\n\nOnly a register of what it did: `${XDG_DATA_HOME:-~/.local/share}/mcp-servers/pdf/operations.json`, the last 500\noperations, as plain JSON. Your PDFs stay where you put them. Every write to the register runs inside an advisory\nlock on `.../pdf/.lock`, so two clients on one data directory cannot lose a record, and saves go to a temporary file\nand are renamed into place.\n\nIf the register is unreadable or not valid JSON it is never treated as \"empty\": it is moved aside byte-for-byte as\n`operations.json.corrupt-` with a marker beside it. The PDF you asked for is still written -- the file is\non disk before the register is touched -- and the answer tells you the history could not be updated.\n\nThe business footer reads the one shared profile the whole suite uses,\n`${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json`, written by `business_set` in mcp-invoice or\nmcp-docx. Nothing is invented: with no name stored, `pdf_watermark_business` refuses and says which tool to run.\n\n## Privacy\n\nAll data stays local. The server reads and writes files on your machine and makes no network request of any kind --\nnot for licensing (keys are verified offline), not for fonts, not for telemetry. A PDF you stamp is never uploaded\nanywhere, which is the entire reason this exists.\n\n## Pairs with\n\n- [mcp-invoice](../invoice/README.md) -- the invoice you sent, stamped PAID: the `mark_invoice_paid` prompt chains `invoice_get` into `pdf_stamp`.\n- [mcp-docx](../docx/README.md) -- write the proposal as `.docx`, print it to PDF, then stamp, merge or split it here.\n- [mcp-resume](../resume/README.md) -- join a CV, a cover letter and a portfolio into the one file an application form accepts.\n- [office-suite](../office-suite/README.md) -- several servers behind one install, one config entry.\n\n## Troubleshooting\n\n- **`npx` hangs or fails to find the package**: npm publish for this package is pending. Use the `.mcpb` bundle or the\n clone-and-build path above until it lands.\n- **\"is encrypted and was refused\"**: the file is password or permissions protected. Open it in a PDF reader, export\n or print to a new PDF, and run the tool on that copy. This server never guesses or strips a password.\n- **`pdf_text` returned nothing**: the page is a scan, or its font uses a custom encoding. The answer says which.\n There is no OCR here.\n- **The stamp is too small or too big**: by default it is sized to fit the page width. Pass `font_size` for an exact\n point size, and `opacity` between 0 and 1.\n- **\"already exists and nothing was written\"**: pass `overwrite: true`, or a different `out_path`.\n- **Node version**: requires Node >= 18. Check with `node -v`.\n\nMIT licensed. Support: support@zovo.one\n\nBuilt by [theluckystrike](https://github.com/theluckystrike).\n", "bytes": 16099, "sha": "dc369a898d0ceb928b1b6ba8df0f606190fafb59f949ea1b7cc2a705d1b95858", "repo_slug": "theluckystrike/mcp-pdf", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_theluckystrike_mcp_pdf_c0f3ac83/readme" }