{ "markdown": "\n
\n \"pdf-suite-mcp\"\n
\n\n# pdf-suite-mcp\n\nA comprehensive MCP (Model Context Protocol) server for PDF operations. **37 tools** for reading, searching, creating, merging, splitting, watermarking, stamping, form filling, redacting, annotating, comparing, optimizing, and more.\n\nBuilt on open-source libraries — **not affiliated with Adobe**. Uses [pdf-lib](https://pdf-lib.js.org/) for PDF manipulation and [unpdf](https://github.com/nicbou/unpdf) (Mozilla pdf.js) for text extraction.\n\n## Requirements\n\n- **Node.js >= 18** (tested on Node 18, 20, 22, 24)\n- npm or compatible package manager\n\n## Installation\n\n```bash\ngit clone https://github.com/beepboop2025/pdf-suite-mcp.git\ncd pdf-suite-mcp\nnpm install\nnpm run build\n```\n\n## Configuration\n\n### Claude Code (one line, no clone)\n\n```sh\nclaude mcp add pdf-suite -- npx -y pdf-suite-mcp\n```\n\n### Any MCP client\n\nAdd to your client's MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"pdf-suite\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"pdf-suite-mcp\"]\n }\n }\n}\n```\n\n### From a local clone\n\n```json\n{\n \"mcpServers\": {\n \"pdf-suite\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/pdf-suite-mcp/dist/index.js\"]\n }\n }\n}\n```\n\n## Tools Overview\n\n| Category | Tools | Count |\n|----------|-------|-------|\n| **Read** | Extract text (per-page), PDF info & metadata | 2 |\n| **Search** | Full-text search with context, compare two PDFs | 2 |\n| **Create** | Generate PDFs from text (with headings), images to PDF | 2 |\n| **Manipulate** | Merge, split, rotate, delete, extract, reorder, insert, reverse, blank pages, crop, overlay PDF, N-up page layout | 12 |\n| **Overlay** | Watermark, page numbers, add text, add image, headers/footers, business stamps, signatures | 7 |\n| **Annotate** | Redact regions, highlight, draw shapes (rect/line/ellipse) | 3 |\n| **Forms** | Read form fields, fill forms (text/checkbox/dropdown/radio) | 2 |\n| **Metadata** | Set title, author, subject, keywords, creator, producer | 1 |\n| **Security** | Decrypt password-protected PDFs | 1 |\n| **Optimize** | Flatten forms, compress, validate, repair | 4 |\n| **Attachments** | Embed files inside a PDF | 1 |\n\n## Tool Reference\n\n### Reading\n\n**`pdf_read_text`** — Extract text from all or specific pages.\n- `filePath` (string, required) — PDF path\n- `pages` (number[], optional) — Page numbers to extract (1-indexed). Returns per-page text with headers.\n\n**`pdf_info`** — Page count, file size, all metadata, form field count, page dimensions (pts + inches), rotation, PDF version.\n- `filePath` (string, required) — PDF path\n- `password` (string, optional) — For encrypted PDFs\n\n### Searching\n\n**`pdf_search`** — Full-text search across all pages. Returns matches with page numbers and surrounding context.\n- `filePath` (string, required) — PDF path\n- `query` (string, required) — Text or regex pattern\n- `caseSensitive` (boolean, default: false)\n- `regex` (boolean, default: false) — Treat query as regex\n- `contextChars` (number, default: 60) — Characters of context around each match\n\n**`pdf_compare`** — Compare text content of two PDFs page by page. Reports identical/different pages with word-level change summary.\n- `filePath1`, `filePath2` (strings, required)\n\n### Creating\n\n**`pdf_create`** — Create a PDF from text with auto word-wrapping, pagination, and headings.\n- `outputPath`, `content` (required) — Lines starting with `# ` render as bold headings\n- `fontSize` (default: 12), `margin` (50), `lineSpacing` (1.4)\n- `pageSize`: A4, Letter, Legal, A3, A5\n- `font`: Helvetica, TimesRoman, Courier\n- `title`, `author` (optional metadata)\n\n**`pdf_images_to_pdf`** — Convert PNG/JPG images to a PDF, one per page.\n- `imagePaths` (string[], required), `outputPath` (required)\n- `pageSize`: A4, Letter, Legal, FitImage (default: A4)\n- `margin` (default: 0) — Padding around image\n\n### Manipulating\n\n**`pdf_merge`** — Merge multiple PDFs.\n- `filePaths` (string[], min 2), `outputPath`\n\n**`pdf_split`** — Split into individual pages or custom ranges.\n- `filePath`, `outputDir`\n- `ranges` (optional) — `[{start, end}]` (1-indexed, inclusive). Omit to split into individual pages.\n\n**`pdf_rotate`** — Rotate pages 90/180/270 degrees clockwise.\n- `filePath`, `outputPath`, `rotation` (\"90\"/\"180\"/\"270\")\n- `pages` (optional) — Omit for all pages\n\n**`pdf_delete_pages`** — Remove specific pages.\n- `filePath`, `outputPath`, `pages` (number[], required)\n\n**`pdf_extract_pages`** — Extract specific pages into a new PDF.\n- `filePath`, `outputPath`, `pages` (number[], required)\n\n**`pdf_reorder`** — Reorder or duplicate pages.\n- `filePath`, `outputPath`, `pageOrder` (number[]) — e.g. `[3, 1, 2]` or `[1, 1, 2]` to duplicate page 1\n\n**`pdf_insert_pages`** — Insert pages from one PDF into another at a specific position.\n- `targetPath`, `sourcePath`, `outputPath`\n- `insertAfter` (number) — 0 = beginning, use target page count for end\n- `sourcePages` (number[], optional) — Which source pages to take. Omit for all.\n\n**`pdf_reverse`** — Reverse page order.\n- `filePath`, `outputPath`\n\n**`pdf_blank_pages`** — Insert blank pages after specified positions.\n- `filePath`, `outputPath`\n- `afterPages` (number[]) — e.g. `[0, 3]` inserts blanks at the beginning and after page 3\n- `pageSize`: MatchPrevious (default), A4, Letter, Legal\n\n**`pdf_crop`** — Crop pages by setting a crop box (does not resize, hides content outside the box).\n- `filePath`, `outputPath`, `x`, `y`, `width`, `height` (all in points)\n- `pages` (optional)\n\n**`pdf_overlay_pdf`** — Overlay a single page from one PDF on top of another. Uses a single overlay page applied to selected base pages — not a page-by-page multi-page overlay.\n- `basePath` (background), `overlayPath` (foreground), `outputPath`\n- `overlayPage` (default: 1) — Which overlay page to use\n- `pages` (optional) — Which base pages to apply it to\n\n**`pdf_page_layout`** — Arrange multiple pages onto single sheets (N-up printing). Scales and positions source pages into a 2-up or 4-up grid.\n- `filePath`, `outputPath`\n- `layout`: \"2-up\" (2 pages side-by-side) or \"4-up\" (2×2 grid)\n- `pageSize`: A4, Letter, Legal (default: Letter)\n\n### Overlays\n\n**`pdf_watermark`** — Diagonal text watermark, properly centered regardless of rotation angle.\n- `filePath`, `outputPath`, `text` (required)\n- `opacity` (0.15), `fontSize` (60), `color` (#888888), `rotation` (45 degrees)\n- `pages` (optional)\n\n**`pdf_page_numbers`** — Add page numbers to every page.\n- `filePath`, `outputPath`\n- `position`: bottom-center (default), bottom-left, bottom-right, top-center, top-left, top-right\n- `startNumber` (1), `prefix` (\"\"), `suffix` (\"\"), `fontSize` (10), `margin` (30), `color` (#4d4d4d)\n\n**`pdf_add_text`** — Add text at exact coordinates. Supports multi-line (`\\n`) and bold fonts.\n- `filePath`, `outputPath`, `text`, `page`, `x`, `y`\n- `fontSize` (12), `color` (black), `lineSpacing` (1.4)\n- `font`: Helvetica, HelveticaBold, TimesRoman, TimesRomanBold, Courier, CourierBold\n\n**`pdf_add_image`** — Add PNG/JPG at exact coordinates.\n- `filePath`, `outputPath`, `imagePath`, `page`, `x`, `y`\n- `width`, `height` (proportional scaling if only one given; original size if both omitted)\n- `opacity` (1)\n\n**`pdf_header_footer`** — Headers and/or footers with dynamic placeholders.\n- `filePath`, `outputPath`\n- `header`, `footer` — Use `{page}` for current page, `{pages}` for total\n- `fontSize` (9), `margin` (30), `align` (center/left/right), `color` (#4d4d4d)\n\n**`pdf_stamp`** — Styled business stamps with border and rotation.\n- `filePath`, `outputPath`\n- `type`: APPROVED, REJECTED, CONFIDENTIAL, DRAFT, FINAL, COPY, VOID, ORIGINAL, REVISED, FOR REVIEW, CUSTOM\n- `customText` (string, only for CUSTOM type)\n- `position`: top-right (default), top-left, bottom-right, bottom-left, center\n- `pages` (optional), `opacity` (0.75), `rotation` (-15)\n\n**`pdf_sign`** — Add a signature image with smart positioning.\n- `filePath`, `outputPath`, `imagePath`\n- `page` (default: last page)\n- `position`: bottom-right (default), bottom-left, bottom-center\n- `width` (150, height scales proportionally), `margin` (50)\n\n### Annotating\n\n**`pdf_redact`** — Draw opaque rectangles over regions.\n- `filePath`, `outputPath`\n- `regions` — `[{page, x, y, width, height}]`\n- `color` (default: black)\n\n> **WARNING: Visual-only redaction.** This tool covers content with an opaque box but does **NOT** remove the underlying text or data from the PDF structure. The original content can still be extracted programmatically by anyone with a PDF parser. **Do NOT use this for true sanitization of sensitive data** (SSNs, passwords, PII, etc). For secure redaction that strips content from the PDF, use Adobe Acrobat Pro, `qpdf`, or `mutool clean`.\n\n**`pdf_highlight`** — Translucent highlight boxes (like a highlighter pen).\n- `filePath`, `outputPath`\n- `highlights` — `[{page, x, y, width, height, color?}]` (per-highlight color, default: yellow)\n- `opacity` (0.35)\n\n**`pdf_draw`** — Draw shapes: rectangles, lines, and ellipses.\n- `filePath`, `outputPath`\n- `shapes` — array of shape objects:\n - **rectangle:** `{type: \"rectangle\", page, x, y, width, height, color?, borderColor?, borderWidth?, filled?, opacity?}`\n - **line:** `{type: \"line\", page, x, y, width, height}` where x/y = start point, width/height = end point coordinates\n - **ellipse:** `{type: \"ellipse\", page, x, y, width, height, color?, filled?, opacity?}`\n\n### Forms\n\n**`pdf_form_read`** — List all form fields with names, types, current values, and dropdown/radio options.\n- `filePath`, `password` (optional)\n\n**`pdf_form_fill`** — Fill form fields by name. Supports partial fills (unfilled fields remain editable).\n- `filePath`, `outputPath`\n- `fields` — `{\"fieldName\": \"value\"}`. Checkboxes: \"true\"/\"false\". Dropdowns/radio: the option value.\n- `flatten` (default: false) — When true, all fields become non-editable (filled AND unfilled)\n- `password` (optional)\n\n### Metadata\n\n**`pdf_set_metadata`** — Update document metadata. Only specified fields change; others are untouched.\n- `filePath`, `outputPath`\n- `title`, `author`, `subject`, `creator`, `producer` (all optional strings)\n- `keywords` (string[], optional)\n\n### Security\n\n**`pdf_decrypt`** — Remove password protection (requires the correct password).\n- `filePath`, `password`, `outputPath`\n\n### Optimize\n\n**`pdf_flatten`** — Flatten all form fields into static page content. Fields become non-editable. Useful for finalizing documents.\n- `filePath`, `outputPath`\n\n**`pdf_compress`** — Reduce PDF file size by rebuilding document structure. Copies pages to a fresh PDF (dropping orphaned objects), optionally strips metadata and flattens forms. Results vary.\n- `filePath`, `outputPath`\n- `stripMetadata` (boolean, default: false) — Remove title, author, subject, keywords\n- `flattenForms` (boolean, default: false) — Flatten form fields\n\n**`pdf_validate`** — Health check for a PDF file. Checks if it can be parsed, reports page count, metadata, form fields, page dimensions, and any structural issues.\n- `filePath` (string, required)\n\n**`pdf_repair`** — Attempt to repair a damaged PDF by loading with lenient parsing, copying all recoverable pages to a clean document, and re-saving.\n- `filePath` (damaged PDF path), `outputPath`\n\n### Attachments\n\n**`pdf_attach`** — Embed files as attachments inside a PDF. Attached files travel with the PDF and can be extracted by PDF readers. Supports any file type with auto-detected MIME types.\n- `filePath`, `outputPath`\n- `attachments` — `[{path, description?}]` — Files to embed\n- Recognized types: PDF, TXT, CSV, JSON, XML, HTML, PNG, JPG, GIF, SVG, ZIP, DOC/DOCX, XLS/XLSX (others default to `application/octet-stream`)\n\n## Error Handling\n\nAll tools return structured error messages. Common scenarios:\n\n| Scenario | Error Message |\n|----------|--------------|\n| File not found | `Error: ENOENT: no such file or directory, open '/path/to/file.pdf'` |\n| Not a valid PDF | `Error: Failed to read PDF: ...` with parser details |\n| Wrong password | `Error: Incorrect password or the PDF is not encrypted.` |\n| Page out of range | `Error: Page 5 out of range (1-3).` or `No valid pages. PDF has 3 page(s).` |\n| Unsupported image | `Error: Unsupported image format: .webp. Use PNG or JPG.` |\n| Delete all pages | `Error: Cannot delete all pages` |\n| No metadata given | `Error: No metadata fields specified. Provide at least one of: title, author, ...` |\n| Invalid regex | `Error: Invalid regex: ...` |\n| Damaged PDF | `Error: PDF is too damaged to repair: ...` |\n\nTools never throw unhandled exceptions — all errors are caught and returned as MCP error responses with `isError: true`.\n\n## File Size & Performance\n\n- **No hard file size limit** — bounded only by available memory (Node.js heap)\n- PDFs up to ~100MB work reliably; larger files may need `--max-old-space-size`\n- `pdf_merge` with many large files is the most memory-intensive operation\n- `pdf_read_text` loads the entire PDF into memory for parsing\n- All operations are single-threaded (no worker pool)\n\n## Named Colors Reference\n\nAll color parameters (`color`, `borderColor`, highlight `color`, etc.) accept:\n\n| Format | Example |\n|--------|---------|\n| **Hex (6-char)** | `#ff0000` |\n| **Hex (3-char)** | `#f00` |\n| **Named color** | `red` |\n\n**Complete named color list (28 colors):**\n\n| Color | Hex | Color | Hex |\n|-------|-----|-------|-----|\n| black | #000000 | white | #ffffff |\n| red | #ff0000 | green | #00ff00 |\n| blue | #0000ff | yellow | #ffff00 |\n| orange | #ff8800 | purple | #800080 |\n| pink | #ff69b4 | gray / grey | #808080 |\n| cyan / aqua | #00ffff | magenta | #ff00ff |\n| brown | #8b4513 | navy | #000080 |\n| teal | #008080 | maroon | #800000 |\n| olive | #808000 | lime | #00ff00 |\n| coral | #ff7f50 | salmon | #fa8072 |\n| gold | #ffd700 | silver | #c0c0c0 |\n| indigo | #4b0082 | violet | #ee82ee |\n| crimson | #dc143c | tomato | #ff6347 |\n\n## Coordinate System\n\n- Origin: **bottom-left** corner of each page\n- Units: **points** (1 inch = 72 points, 1 cm ~ 28.35 points)\n- Standard page sizes:\n\n| Size | Width | Height | Inches |\n|------|-------|--------|--------|\n| A4 | 595 | 842 | 8.3\" x 11.7\" |\n| Letter | 612 | 792 | 8.5\" x 11\" |\n| Legal | 612 | 1008 | 8.5\" x 14\" |\n| A3 | 842 | 1191 | 11.7\" x 16.5\" |\n| A5 | 420 | 595 | 5.8\" x 8.3\" |\n\n## Limitations\n\n| Feature | Limitation |\n|---------|-----------|\n| **Text extraction** | Text-based PDFs only. No OCR for scanned images. |\n| **Encryption** | Can decrypt (with password) but cannot encrypt/password-protect. |\n| **Image formats** | PNG and JPG only. No WebP, SVG, TIFF, or GIF. |\n| **Fonts** | Helvetica, Times Roman, Courier (standard PDF fonts with bold/italic). No custom font embedding. |\n| **Redaction** | **Visual only** — covers content but does NOT strip data from the PDF. See warning above. |\n| **Overlay** | Single overlay page applied to base pages. Not a page-by-page multi-page overlay. |\n| **Form filling** | Supports partial fills. Flatten affects ALL fields (filled and unfilled). |\n| **Compression** | Rebuilds document structure only — no image downsampling or stream compression. |\n| **Annotations** | Drawn as page content (not PDF annotation objects). Cannot be toggled or removed by PDF viewers. |\n| **Search/Compare** | Text-based comparison only. Cannot detect visual differences in images or layout. |\n\n## Tech Stack\n\n- [pdf-lib](https://pdf-lib.js.org/) — PDF creation and manipulation (open-source, MIT)\n- [unpdf](https://github.com/nicbou/unpdf) — Text extraction via Mozilla's pdf.js (open-source)\n- [@modelcontextprotocol/sdk](https://modelcontextprotocol.io/) — MCP server framework\n\n## Disclaimer\n\nThis project is **not affiliated with, endorsed by, or associated with Adobe Inc.** \"PDF\" is an open standard (ISO 32000). This tool uses open-source libraries to work with PDF files.\n\n## License\n\nMIT\n", "bytes": 15918, "sha": "9ff11929a49c47d3412f86340a614268c6bc7b44268c836ba945ce6e4f48fe4e", "repo_slug": "beepboop2025/pdf-suite-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_beepboop2025_pdf_suite_mcp_336b206c/readme" }