pdf-suite-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pdf-suite-mcp extract pages 1-5 from document.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pdf-suite-mcp
A 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.
Built on open-source libraries — not affiliated with Adobe. Uses pdf-lib for PDF manipulation and unpdf (Mozilla pdf.js) for text extraction.
Requirements
Node.js >= 18 (tested on Node 18, 20, 22, 24)
npm or compatible package manager
Related MCP server: PDF MCP Server
Installation
git clone https://github.com/beepboop2025/pdf-suite-mcp.git
cd pdf-suite-mcp
npm install
npm run buildConfiguration
Claude Code (one line, no clone)
claude mcp add pdf-suite -- npx -y pdf-suite-mcpAny MCP client
Add to your client's MCP config:
{
"mcpServers": {
"pdf-suite": {
"command": "npx",
"args": ["-y", "pdf-suite-mcp"]
}
}
}From a local clone
{
"mcpServers": {
"pdf-suite": {
"command": "node",
"args": ["/path/to/pdf-suite-mcp/dist/index.js"]
}
}
}Tools Overview
Category | Tools | Count |
Read | Extract text (per-page), PDF info & metadata | 2 |
Search | Full-text search with context, compare two PDFs | 2 |
Create | Generate PDFs from text (with headings), images to PDF | 2 |
Manipulate | Merge, split, rotate, delete, extract, reorder, insert, reverse, blank pages, crop, overlay PDF, N-up page layout | 12 |
Overlay | Watermark, page numbers, add text, add image, headers/footers, business stamps, signatures | 7 |
Annotate | Redact regions, highlight, draw shapes (rect/line/ellipse) | 3 |
Forms | Read form fields, fill forms (text/checkbox/dropdown/radio) | 2 |
Metadata | Set title, author, subject, keywords, creator, producer | 1 |
Security | Decrypt password-protected PDFs | 1 |
Optimize | Flatten forms, compress, validate, repair | 4 |
Attachments | Embed files inside a PDF | 1 |
Tool Reference
Reading
pdf_read_text — Extract text from all or specific pages.
filePath(string, required) — PDF pathpages(number[], optional) — Page numbers to extract (1-indexed). Returns per-page text with headers.
pdf_info — Page count, file size, all metadata, form field count, page dimensions (pts + inches), rotation, PDF version.
filePath(string, required) — PDF pathpassword(string, optional) — For encrypted PDFs
Searching
pdf_search — Full-text search across all pages. Returns matches with page numbers and surrounding context.
filePath(string, required) — PDF pathquery(string, required) — Text or regex patterncaseSensitive(boolean, default: false)regex(boolean, default: false) — Treat query as regexcontextChars(number, default: 60) — Characters of context around each match
pdf_compare — Compare text content of two PDFs page by page. Reports identical/different pages with word-level change summary.
filePath1,filePath2(strings, required)
Creating
pdf_create — Create a PDF from text with auto word-wrapping, pagination, and headings.
outputPath,content(required) — Lines starting with#render as bold headingsfontSize(default: 12),margin(50),lineSpacing(1.4)pageSize: A4, Letter, Legal, A3, A5font: Helvetica, TimesRoman, Couriertitle,author(optional metadata)
pdf_images_to_pdf — Convert PNG/JPG images to a PDF, one per page.
imagePaths(string[], required),outputPath(required)pageSize: A4, Letter, Legal, FitImage (default: A4)margin(default: 0) — Padding around image
Manipulating
pdf_merge — Merge multiple PDFs.
filePaths(string[], min 2),outputPath
pdf_split — Split into individual pages or custom ranges.
filePath,outputDirranges(optional) —[{start, end}](1-indexed, inclusive). Omit to split into individual pages.
pdf_rotate — Rotate pages 90/180/270 degrees clockwise.
filePath,outputPath,rotation("90"/"180"/"270")pages(optional) — Omit for all pages
pdf_delete_pages — Remove specific pages.
filePath,outputPath,pages(number[], required)
pdf_extract_pages — Extract specific pages into a new PDF.
filePath,outputPath,pages(number[], required)
pdf_reorder — Reorder or duplicate pages.
filePath,outputPath,pageOrder(number[]) — e.g.[3, 1, 2]or[1, 1, 2]to duplicate page 1
pdf_insert_pages — Insert pages from one PDF into another at a specific position.
targetPath,sourcePath,outputPathinsertAfter(number) — 0 = beginning, use target page count for endsourcePages(number[], optional) — Which source pages to take. Omit for all.
pdf_reverse — Reverse page order.
filePath,outputPath
pdf_blank_pages — Insert blank pages after specified positions.
filePath,outputPathafterPages(number[]) — e.g.[0, 3]inserts blanks at the beginning and after page 3pageSize: MatchPrevious (default), A4, Letter, Legal
pdf_crop — Crop pages by setting a crop box (does not resize, hides content outside the box).
filePath,outputPath,x,y,width,height(all in points)pages(optional)
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.
basePath(background),overlayPath(foreground),outputPathoverlayPage(default: 1) — Which overlay page to usepages(optional) — Which base pages to apply it to
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.
filePath,outputPathlayout: "2-up" (2 pages side-by-side) or "4-up" (2×2 grid)pageSize: A4, Letter, Legal (default: Letter)
Overlays
pdf_watermark — Diagonal text watermark, properly centered regardless of rotation angle.
filePath,outputPath,text(required)opacity(0.15),fontSize(60),color(#888888),rotation(45 degrees)pages(optional)
pdf_page_numbers — Add page numbers to every page.
filePath,outputPathposition: bottom-center (default), bottom-left, bottom-right, top-center, top-left, top-rightstartNumber(1),prefix(""),suffix(""),fontSize(10),margin(30),color(#4d4d4d)
pdf_add_text — Add text at exact coordinates. Supports multi-line (\n) and bold fonts.
filePath,outputPath,text,page,x,yfontSize(12),color(black),lineSpacing(1.4)font: Helvetica, HelveticaBold, TimesRoman, TimesRomanBold, Courier, CourierBold
pdf_add_image — Add PNG/JPG at exact coordinates.
filePath,outputPath,imagePath,page,x,ywidth,height(proportional scaling if only one given; original size if both omitted)opacity(1)
pdf_header_footer — Headers and/or footers with dynamic placeholders.
filePath,outputPathheader,footer— Use{page}for current page,{pages}for totalfontSize(9),margin(30),align(center/left/right),color(#4d4d4d)
pdf_stamp — Styled business stamps with border and rotation.
filePath,outputPathtype: APPROVED, REJECTED, CONFIDENTIAL, DRAFT, FINAL, COPY, VOID, ORIGINAL, REVISED, FOR REVIEW, CUSTOMcustomText(string, only for CUSTOM type)position: top-right (default), top-left, bottom-right, bottom-left, centerpages(optional),opacity(0.75),rotation(-15)
pdf_sign — Add a signature image with smart positioning.
filePath,outputPath,imagePathpage(default: last page)position: bottom-right (default), bottom-left, bottom-centerwidth(150, height scales proportionally),margin(50)
Annotating
pdf_redact — Draw opaque rectangles over regions.
filePath,outputPathregions—[{page, x, y, width, height}]color(default: black)
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, ormutool clean.
pdf_highlight — Translucent highlight boxes (like a highlighter pen).
filePath,outputPathhighlights—[{page, x, y, width, height, color?}](per-highlight color, default: yellow)opacity(0.35)
pdf_draw — Draw shapes: rectangles, lines, and ellipses.
filePath,outputPathshapes— array of shape objects:rectangle:
{type: "rectangle", page, x, y, width, height, color?, borderColor?, borderWidth?, filled?, opacity?}line:
{type: "line", page, x, y, width, height}where x/y = start point, width/height = end point coordinatesellipse:
{type: "ellipse", page, x, y, width, height, color?, filled?, opacity?}
Forms
pdf_form_read — List all form fields with names, types, current values, and dropdown/radio options.
filePath,password(optional)
pdf_form_fill — Fill form fields by name. Supports partial fills (unfilled fields remain editable).
filePath,outputPathfields—{"fieldName": "value"}. Checkboxes: "true"/"false". Dropdowns/radio: the option value.flatten(default: false) — When true, all fields become non-editable (filled AND unfilled)password(optional)
Metadata
pdf_set_metadata — Update document metadata. Only specified fields change; others are untouched.
filePath,outputPathtitle,author,subject,creator,producer(all optional strings)keywords(string[], optional)
Security
pdf_decrypt — Remove password protection (requires the correct password).
filePath,password,outputPath
Optimize
pdf_flatten — Flatten all form fields into static page content. Fields become non-editable. Useful for finalizing documents.
filePath,outputPath
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.
filePath,outputPathstripMetadata(boolean, default: false) — Remove title, author, subject, keywordsflattenForms(boolean, default: false) — Flatten form fields
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.
filePath(string, required)
pdf_repair — Attempt to repair a damaged PDF by loading with lenient parsing, copying all recoverable pages to a clean document, and re-saving.
filePath(damaged PDF path),outputPath
Attachments
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.
filePath,outputPathattachments—[{path, description?}]— Files to embedRecognized types: PDF, TXT, CSV, JSON, XML, HTML, PNG, JPG, GIF, SVG, ZIP, DOC/DOCX, XLS/XLSX (others default to
application/octet-stream)
Error Handling
All tools return structured error messages. Common scenarios:
Scenario | Error Message |
File not found |
|
Not a valid PDF |
|
Wrong password |
|
Page out of range |
|
Unsupported image |
|
Delete all pages |
|
No metadata given |
|
Invalid regex |
|
Damaged PDF |
|
Tools never throw unhandled exceptions — all errors are caught and returned as MCP error responses with isError: true.
File Size & Performance
No hard file size limit — bounded only by available memory (Node.js heap)
PDFs up to ~100MB work reliably; larger files may need
--max-old-space-sizepdf_mergewith many large files is the most memory-intensive operationpdf_read_textloads the entire PDF into memory for parsingAll operations are single-threaded (no worker pool)
Named Colors Reference
All color parameters (color, borderColor, highlight color, etc.) accept:
Format | Example |
Hex (6-char) |
|
Hex (3-char) |
|
Named color |
|
Complete named color list (28 colors):
Color | Hex | Color | Hex |
black | #000000 | white | #ffffff |
red | #ff0000 | green | #00ff00 |
blue | #0000ff | yellow | #ffff00 |
orange | #ff8800 | purple | #800080 |
pink | #ff69b4 | gray / grey | #808080 |
cyan / aqua | #00ffff | magenta | #ff00ff |
brown | #8b4513 | navy | #000080 |
teal | #008080 | maroon | #800000 |
olive | #808000 | lime | #00ff00 |
coral | #ff7f50 | salmon | #fa8072 |
gold | #ffd700 | silver | #c0c0c0 |
indigo | #4b0082 | violet | #ee82ee |
crimson | #dc143c | tomato | #ff6347 |
Coordinate System
Origin: bottom-left corner of each page
Units: points (1 inch = 72 points, 1 cm ~ 28.35 points)
Standard page sizes:
Size | Width | Height | Inches |
A4 | 595 | 842 | 8.3" x 11.7" |
Letter | 612 | 792 | 8.5" x 11" |
Legal | 612 | 1008 | 8.5" x 14" |
A3 | 842 | 1191 | 11.7" x 16.5" |
A5 | 420 | 595 | 5.8" x 8.3" |
Limitations
Feature | Limitation |
Text extraction | Text-based PDFs only. No OCR for scanned images. |
Encryption | Can decrypt (with password) but cannot encrypt/password-protect. |
Image formats | PNG and JPG only. No WebP, SVG, TIFF, or GIF. |
Fonts | Helvetica, Times Roman, Courier (standard PDF fonts with bold/italic). No custom font embedding. |
Redaction | Visual only — covers content but does NOT strip data from the PDF. See warning above. |
Overlay | Single overlay page applied to base pages. Not a page-by-page multi-page overlay. |
Form filling | Supports partial fills. Flatten affects ALL fields (filled and unfilled). |
Compression | Rebuilds document structure only — no image downsampling or stream compression. |
Annotations | Drawn as page content (not PDF annotation objects). Cannot be toggled or removed by PDF viewers. |
Search/Compare | Text-based comparison only. Cannot detect visual differences in images or layout. |
Tech Stack
pdf-lib — PDF creation and manipulation (open-source, MIT)
unpdf — Text extraction via Mozilla's pdf.js (open-source)
@modelcontextprotocol/sdk — MCP server framework
Disclaimer
This 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.
License
MIT
Available Tools
37 toolspdf_add_imageA
Add an image (PNG/JPG) at a position on a page. Aspect ratio is preserved when only width or height is given.
Inputs: x (required), y (required), page (required), filePath (required), +5 more.
pdf_add_textB
Add text at a specific position on a PDF page. Supports multi-line text (use \n). Coordinates are in points from bottom-left.
Inputs: x (required), y (required), page (required), text (required), +6 more.
pdf_attachA
Embed one or more files as attachments inside a PDF. Attached files travel with the PDF and can be extracted by PDF readers. Useful for bundling source data, receipts, supporting documents, etc.
Inputs: filePath (required), outputPath (required), attachments (required).
pdf_blank_pagesA
Insert blank pages into a PDF at specified positions. Useful for adding separator pages or ensuring chapters start on odd pages.
Inputs: filePath (required), afterPages (required), outputPath (required), pageSize.
pdf_compareA
Compare the text content of two PDFs page by page. Reports which pages are identical, which differ, and shows a summary of differences. Useful for verifying document versions.
Inputs: filePath1 (required), filePath2 (required).
pdf_compressA
Attempt to reduce PDF file size by rebuilding the document structure. Copies all pages to a fresh PDF (dropping orphaned objects), and optionally strips metadata. Results vary — works best on PDFs with accumulated edits or orphaned data.
Inputs: filePath (required), outputPath (required), flattenForms, stripMetadata.
pdf_createA
Create a new PDF from text. Supports auto word-wrapping, pagination, bold/italic, configurable fonts, margins, page sizes. Lines starting with "# " render as bold headings.
Inputs: content (required), outputPath (required), font, title, +5 more.
pdf_cropA
Crop pages by setting the visible area (crop box). Trims margins or isolates a region. Coordinates are in points from bottom-left.
Inputs: x (required), y (required), width (required), height (required), +3 more.
pdf_decryptA
Remove password protection from an encrypted PDF. Requires the correct password. Saves an unencrypted copy that can be opened without a password.
Inputs: filePath (required), password (required), outputPath (required).
pdf_delete_pagesC
Remove specific pages from a PDF.
Inputs: pages (required), filePath (required), outputPath (required).
pdf_drawA
Draw shapes on PDF pages: rectangles (filled or outlined), lines, and circles/ellipses. Useful for annotations, diagrams, or marking up documents.
Inputs: shapes (required), filePath (required), outputPath (required).
pdf_extract_pagesC
Extract specific pages into a new PDF.
Inputs: pages (required), filePath (required), outputPath (required).
pdf_flattenA
Flatten a PDF — converts all form fields and annotations into static page content. Fields become non-editable. Useful for finalizing documents before distribution.
Inputs: filePath (required), outputPath (required).
pdf_form_fillA
Fill form fields in a PDF by name. Supports text fields, checkboxes ("true"/"false"), dropdowns, option lists, and radio groups. Use pdf_form_read first to discover field names and types. Optionally flatten the form to make it non-editable.
Inputs: fields (required), filePath (required), outputPath (required), flatten, +1 more.
pdf_form_readA
Read all form fields from a PDF. Returns each field's name, type (Text, CheckBox, Dropdown, OptionList, RadioGroup), current value, and available options. Use this before pdf_form_fill to discover field names.
Inputs: filePath (required), password.
pdf_highlightA
Add translucent highlight boxes over regions on PDF pages — like using a highlighter pen. Great for marking important sections.
Inputs: filePath (required), highlights (required), outputPath (required), opacity.
pdf_images_to_pdfA
Convert one or more images (PNG/JPG) into a PDF. Each image becomes a page, scaled to fit while maintaining aspect ratio.
Inputs: imagePaths (required), outputPath (required), margin, pageSize.
pdf_infoA
Get detailed information about a PDF: page count, file size, metadata (title, author, dates), form field count, and page dimensions in points and inches.
Inputs: filePath (required), password.
pdf_insert_pagesB
Insert pages from one PDF into another at a specific position. Useful for adding cover pages, appendices, or inserting content mid-document.
Inputs: outputPath (required), sourcePath (required), targetPath (required), insertAfter (required), +1 more.
pdf_mergeB
Merge multiple PDF files into a single PDF. Pages are combined in the order listed.
Inputs: filePaths (required), outputPath (required).
pdf_overlay_pdfB
Overlay one PDF on top of another. The overlay PDF is drawn on top of the base PDF pages. Perfect for adding letterheads, templates, or watermark PDFs.
Inputs: basePath (required), outputPath (required), overlayPath (required), pages, +1 more.
pdf_page_layoutA
Arrange multiple PDF pages onto single sheets in N-up layouts. Puts 2 or 4 source pages onto each output page side-by-side. Useful for printing handouts, saving paper, or creating thumbnail sheets.
Inputs: layout (required), filePath (required), outputPath (required), pageSize.
pdf_page_numbersB
Add page numbers to every page. Supports various positions, custom prefix/suffix, and starting number.
Inputs: filePath (required), outputPath (required), color, margin, +5 more.
pdf_read_textA
Extract text content from a PDF file. Can extract from all pages or specific pages. Works with text-based PDFs (not scanned images).
Inputs: filePath (required), pages.
pdf_redactA
VISUAL-ONLY redaction: draws opaque rectangles over regions on PDF pages. WARNING: This does NOT remove the underlying text/data from the PDF — it only covers it visually. The original content can still be extracted programmatically. Do NOT use this for true document sanitization of sensitive data (SSNs, passwords, etc). For true redaction, use a tool that rewrites the PDF content stream (e.g. Adobe Acrobat Pro, qpdf, or mutool).
Inputs: regions (required), filePath (required), outputPath (required), color.
pdf_reorderB
Reorder pages. Can also duplicate pages by repeating numbers in the order array.
Inputs: filePath (required), pageOrder (required), outputPath (required).
pdf_repairA
Attempt to repair a damaged or malformed PDF by loading it with lenient parsing, copying all recoverable pages to a clean document, and re-saving. May fix issues like corrupted cross-reference tables or orphaned objects.
Inputs: filePath (required), outputPath (required).
pdf_reverseA
Reverse the page order of a PDF. Useful for fixing scan order or printing back-to-front.
Inputs: filePath (required), outputPath (required).
pdf_rotateA
Rotate pages by 90, 180, or 270 degrees clockwise.
Inputs: filePath (required), rotation (required), outputPath (required), pages.
pdf_searchA
Search for text in a PDF. Returns all matches with page numbers and surrounding context. Supports plain text and regex search.
Inputs: query (required), filePath (required), regex, contextChars, +1 more.
pdf_set_metadataA
Set or update PDF document metadata fields: title, author, subject, keywords, creator, and producer. Only specified fields are changed; others remain untouched.
Inputs: filePath (required), outputPath (required), title, author, +4 more.
pdf_signA
Add a signature image to a PDF with smart positioning. Simplified alternative to pdf_add_image for signing documents.
Inputs: filePath (required), imagePath (required), outputPath (required), page, +3 more.
pdf_splitA
Split a PDF into multiple files — either individual pages or custom page ranges.
Inputs: filePath (required), outputDir (required), ranges.
pdf_stampA
Apply a styled business stamp (like a rubber stamp) to PDF pages. Pre-configured styles for common stamps, or create custom ones. Draws a bordered rectangle with text inside, slightly rotated for authenticity.
Inputs: type (required), filePath (required), outputPath (required), pages, +4 more.
pdf_validateA
Validate a PDF file — checks if it can be parsed, reports page count, metadata, form fields, and any structural issues. Useful as a health check before processing.
Inputs: filePath (required).
pdf_watermarkB
Add a diagonal text watermark across PDF pages. The text is properly centered regardless of rotation angle.
Inputs: text (required), filePath (required), outputPath (required), color, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Most tools have distinct purposes, but there is slight overlap between pdf_extract_pages and pdf_split, and between pdf_overlay_pdf and pdf_watermark. Descriptions help disambiguate, so agents can generally select correctly.
All tools follow the same consistent pattern: prefix 'pdf_' followed by a descriptive verb_noun in snake_case (e.g., pdf_add_image, pdf_merge, pdf_validate). No mixing of conventions.
37 tools is on the higher side, but each covers a distinct PDF operation, from creation to manipulation to validation. The set feels comprehensive rather than bloated, though a few tools could be simplified.
The toolset covers a wide range of PDF lifecycle operations: create, read, edit, annotate, merge/split, form handling, security, metadata, and more. The only notable gap is OCR for scanned documents, which is beyond typical scope. The redaction tool is visual-only, but the description warns clearly.
Maintenance
Related MCP Connectors
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
MCP server for Api2Pdf — generate PDFs & images from HTML, URLs or office files; merge, barcodes.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Privacy-first PDF tools over MCP: merge, split, rotate, delete, compress, protect, inspect.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that provides comprehensive PDF processing capabilities including text extraction, image extraction, table detection, annotation extraction, metadata retrieval, page rendering, and document structure analysis.-
- AlicenseNot gradedqualityBmaintenanceAn MCP server for PDF form filling, basic editing, and OCR text extraction. It enables users to merge, rotate, annotate, and sign PDFs, while also supporting text extraction from both searchable and scanned image-based documents.15Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for reading, writing, and manipulating PDF files, including text extraction, metadata retrieval, and merging or splitting documents. It also enables users to create PDFs from plain text and convert specific pages or entire documents into images.39 npm1ISC
- AlicenseAqualityDmaintenanceAn MCP server for local PDF manipulation including merging, splitting, rotating, watermarking, and text extraction. It works with various MCP-compatible clients and processes PDFs entirely on-device without cloud services.1118 npmMIT