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.
- Node.js >= 18 (tested on Node 18, 20, 22, 24)
- npm or compatible package manager
git clone https://github.com/beepboop2025/pdf-toolkit-mcp.git
cd pdf-toolkit-mcp
npm install
npm run buildAdd to ~/.claude/settings.json:
{
"mcpServers": {
"pdf-toolkit": {
"command": "node",
"args": ["/path/to/pdf-toolkit-mcp/dist/index.js"]
}
}
}{
"mcpServers": {
"pdf-toolkit": {
"command": "npx",
"args": ["tsx", "/path/to/pdf-toolkit-mcp/src/index.ts"]
}
}
}| 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 |
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
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)
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
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)
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)
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 coordinates - ellipse:
{type: "ellipse", page, x, y, width, height, color?, filled?, opacity?}
- rectangle:
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)
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)
pdf_decrypt — Remove password protection (requires the correct password).
filePath,password,outputPath
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
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 embed- Recognized types: PDF, TXT, CSV, JSON, XML, HTML, PNG, JPG, GIF, SVG, ZIP, DOC/DOCX, XLS/XLSX (others default to
application/octet-stream)
All tools return structured error messages. Common scenarios:
| Scenario | Error Message |
|---|---|
| File not found | Error: ENOENT: no such file or directory, open '/path/to/file.pdf' |
| Not a valid PDF | Error: Failed to read PDF: ... with parser details |
| Wrong password | Error: Incorrect password or the PDF is not encrypted. |
| Page out of range | Error: Page 5 out of range (1-3). or No valid pages. PDF has 3 page(s). |
| Unsupported image | Error: Unsupported image format: .webp. Use PNG or JPG. |
| Delete all pages | Error: Cannot delete all pages |
| No metadata given | Error: No metadata fields specified. Provide at least one of: title, author, ... |
| Invalid regex | Error: Invalid regex: ... |
| Damaged PDF | Error: PDF is too damaged to repair: ... |
Tools never throw unhandled exceptions — all errors are caught and returned as MCP error responses with isError: true.
- 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-size pdf_mergewith many large files is the most memory-intensive operationpdf_read_textloads the entire PDF into memory for parsing- All operations are single-threaded (no worker pool)
All color parameters (color, borderColor, highlight color, etc.) accept:
| Format | Example |
|---|---|
| Hex (6-char) | #ff0000 |
| Hex (3-char) | #f00 |
| Named color | red |
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 |
- 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" |
| 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. |
- pdf-lib — PDF creation and manipulation (open-source, MIT)
- unpdf — Text extraction via Mozilla's pdf.js (open-source)
- @modelcontextprotocol/sdk — MCP server framework
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.
MIT