Skip to main content
Glama
pdf-mcp

pdf-mcp

pdf-mcp

Full-stack PDF intelligence MCP server — extract, manipulate, annotate, convert, validate, and RAG-search PDFs through a unified tool surface and React workbench.

v0.2.1 · Ports 11130 (frontend) / 11131 (backend)

FastMCP 3.4.4 · PyMuPDF + pypdf + pdfplumber · LanceDB RAG · Prefab UI · dual transport (stdio + HTTP)

Features

  • pdf_extract — text, images, tables, metadata, fonts, links, outline

  • pdf_manipulate — merge, split, rotate, reorder, delete pages, compress, encrypt/decrypt, optimize

  • pdf_annotate — watermark, stamp, highlight, underline, header/footer, page numbers, auto summary box

  • pdf_forms — list / fill / flatten / export + LLM-guided auto-fill

  • pdf_convert — PDF ↔ Markdown / images / HTML

  • pdf_validate — PDF/A, structure, accessibility, integrity, compare

  • pdf_rag — chunk (table-aware), index (LanceDB), semantic search, query-by-example, cross-document synthesis

  • pdf_analyze / pdf_redact / pdf_classify / pdf_dedupe / pdf_export — intelligence tools

  • pdf_do — autonomous agent that chains the tools from natural language

  • pdf_help / pdf_status / pdf_shutdown — meta tools

Related MCP server: pdf-mcp

Quick start

git clone https://github.com/sandraschi/pdf-mcp
cd pdf-mcp
uv sync
Copy-Item .env.example .env
.\start.ps1

Dashboard: http://127.0.0.1:11130 · MCP/API: http://127.0.0.1:11131

Stack

  • Backend: Python 3.12, FastMCP 3.4.4, Starlette (HTTP), PyMuPDF, pypdf, pdfplumber, LanceDB, Prefab UI

  • Frontend: React 18, Vite 5, Tailwind CSS, Lucide, Framer Motion, Zustand, PDF.js, Playwright

  • Tooling: uv, bun, just, ruff, pyright, Biome, pre-commit

MCP tools

Tool

Operations

pdf_extract

text, images, tables, metadata, fonts, links, outline

pdf_manipulate

merge, split, rotate, reorder, delete_pages, compress, encrypt, decrypt, optimize

pdf_annotate

watermark, stamp, highlight, underline, header_footer, page_numbers, summary_box

pdf_forms

list_fields, fill, flatten, export_data, auto_fill

pdf_convert

to_markdown, to_images, to_html, from_html, from_markdown, from_images

pdf_validate

pdfa, structure, accessibility, integrity, compare

pdf_rag

chunk, index, search, similar, synthesize, list_documents, delete_index

pdf_analyze / pdf_redact / pdf_classify / pdf_dedupe / pdf_export

intelligence

pdf_do

agentic chaining

pdf_help / pdf_status / pdf_shutdown

meta

Claude Desktop config

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "uv",
      "args": ["--directory", "D:\\Dev\\repos\\pdf-mcp", "run", "python", "run_server.py"]
    }
  }
}

For HTTP mode instead: uv run python run_server.py --mode http --port 11131 and connect over http://127.0.0.1:11131/mcp.

Configuration

See docs/CONFIGURATION.md. Key vars: MCP_MODE (stdio/http), MCP_PORT (11131), FRONTEND_PORT (11130), RAG_STORE_PATH, UPLOAD_DIR.

Webapp

Route

Page

/

Dashboard (KPIs, LLM availability, usage stats)

/workbench

PDF.js viewer + OCR badge + compare mode + tool palette

/pipeline

Single operations + multi-step recipes + share links

/chat

LLM chat with PDF search + source citations

/tools / /skills / /logs

Discovery & logs

Documentation

License

MIT

Available Tools

16 tools
pdf_analyzeB
Read-only

Detect whether a PDF has a text layer (digital) or is scanned, with layout stats.

Return Format

A dict with keys:

  • success: bool

  • pages: int

  • has_text_layer: bool - true when average chars per page >= 80

  • scanned: bool - low text + images present

  • chars_per_page: float

  • total_chars: int

  • image_count: int

  • layout_hint: str - digital | scanned | empty

  • per_page: list of {page, chars, images}

Examples

await pdf_analyze(path="scan.pdf") {"success": true, "pages": 5, "has_text_layer": false, "scanned": true, "chars_per_page": 12.4, "image_count": 5, "layout_hint": "scanned", "per_page": [...]}

Inputs: path (required). Returns: message, success

pdf_annotateA

Add annotations and markup to PDFs.

Watermark, stamp, highlight, underline, header/footer, and page numbers.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • watermark/stamp/header_footer/page_numbers: {path}

    • highlight: {path, occurrences}

    • underline: {path, occurrences} On failure: {success: False, error, error_type}.

Examples

await pdf_annotate(operation="watermark", path="report.pdf", text="CONFIDENTIAL", opacity=0.3) {"success": true, "path": ".../report_watermark_....pdf", "message": "Added watermark to report.pdf, saved to report_watermark_....pdf."}

await pdf_annotate(operation="highlight", path="report.pdf", search_text="revenue") {"success": true, "path": ".../report_highlight_....pdf", "occurrences": 3, "message": "Highlighted 3 occurrences of 'revenue' in report.pdf."}

Inputs: path (required), operation (required), x, y, +12 more. Returns: message, success

pdf_classifyB
Read-only

Guess the document type (invoice, report, contract, ...) and extract candidate fields.

Return Format

A dict with keys:

  • success: bool

  • doc_type: str

  • confidence: float (0-1)

  • fields: dict of detected fields (invoice_number, total, date, vendor)

  • reasons: list of matched signals

  • llm_refined: bool - whether the local LLM confirmed the guess

Examples

await pdf_classify(path="invoice_42.pdf") {"success": true, "doc_type": "invoice", "confidence": 0.75, "fields": {"invoice_number": "INV-42", "total": "1,240.00"}, "reasons": ["invoice(x2)"]}

Inputs: path (required), refine. Returns: message, success

pdf_convertB

Convert between PDF and other formats.

PDF to/from Markdown, HTML, and images.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • to_markdown: {markdown, pages}

    • to_images: {images: [{page, path, width, height}]}

    • to_html: {html}

    • from_html/from_markdown/from_images: {path, pages} On failure: {success: False, error, error_type}.

Examples

await pdf_convert(operation="to_markdown", path="report.pdf") {"success": true, "markdown": "# Report...", "pages": 3, "message": "Converted report.pdf to markdown (3 pages)."}

await pdf_convert(operation="from_markdown", markdown="# Hello") {"success": true, "path": ".../output_from_markdown_....pdf", "pages": 1, "message": "Created PDF from markdown (1 pages), saved to output_from_markdown_....pdf."}

Inputs: operation (required), dpi, fmt, html, +5 more. Returns: message, success

pdf_dedupeB
Read-only

Detect exact and near-duplicate PDFs by content fingerprint.

Return Format

A dict with keys:

  • success: bool

  • files: list of input file names

  • exact_duplicates: [{sha, count, files}]

  • near_duplicates: [{a, b, similarity}]

Examples

await pdf_dedupe(paths=["a.pdf", "b.pdf"]) {"success": true, "files": ["a.pdf", "b.pdf"], "exact_duplicates": [], "near_duplicates": [{"a": "a.pdf", "b": "b.pdf", "similarity": 0.92}]}

Inputs: paths (required), threshold. Returns: message, success

pdf_doA

Chain the PDF tools autonomously to complete a natural-language task.

Requires a local LLM (Ollama or LM Studio) or a client that supports MCP sampling. The LLM plans up to 6 tool calls from the pdf_* surface, the server answer. pdf_do cannot call itself or pdf_shutdown.

Return Format

A dict with keys:

  • success: bool

  • answer: str - final natural-language answer

  • steps: list of {tool, args, result} execution records On failure: {success: False, error}.

Examples

await pdf_do(task="Summarize this report and check it for PII.", path="report.pdf") {"success": true, "answer": "The report covers Q3 results... 3 PII hits found.", "steps": [{"tool": "pdf_export", ...}]}

Inputs: task (required), path. Returns: message, success

pdf_exportB

Build a reusable document brief (markdown or JSON) with headings, key terms, and optional summary.

Return Format

A dict with keys:

  • success: bool

  • path: str - brief file path

  • pages: int

  • summary: str | None

Examples

await pdf_export(path="report.pdf", format="markdown") {"success": true, "path": ".../report_brief.md", "pages": 12, "summary": "..."}

Inputs: path (required), format, include_summary. Returns: message, success

pdf_extractB
Read-only

Extract content and metadata from a PDF.

Supports text, images, tables, metadata, fonts, links, and outline extraction through a single portmanteau tool.

Args are validated and documented via Annotated fields on the signature.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • text: {text, pages, page_count}

    • images: {images: [{page, index, width, height, path, ext}]}

    • tables: {tables: [{page, rows, cols, headers, data}]}

    • metadata: {metadata: {...}}

    • fonts: {fonts: [{name, type, encoding, embedded, size}]}

    • links: {links: [{page, uri, page_target, rect}]}

    • outline: {outline: [{title, level, page, children}]} On failure: {success: False, error, error_type}.

Examples

await pdf_extract(operation="text", path="report.pdf", pages="1-3") {"success": true, "text": "...", "pages": 3, "page_count": 12, "message": "Extracted 3 pages of text from report.pdf."}

await pdf_extract(operation="metadata", path="report.pdf") {"success": true, "metadata": {"title": "Report", ...}, "message": "Extracted metadata from report.pdf."}

Inputs: path (required), operation (required), pages. Returns: message, success

pdf_formsC
Read-only

Handle interactive form fields.

List, fill, flatten, export, and auto-fill (LLM-guided) PDF form fields.

Return Format

A dict with keys:

  • success: bool

  • message: str - human-readable summary

  • operation-specific keys:

    • list_fields: {fields: [{name, type, value, page, rect}]}

    • fill/flatten: {path}

    • export_data: {data: {field_name: value}}

    • auto_fill: {path, filled, missing} On failure: {success: False, error, error_type}.

Examples

await pdf_forms(operation="list_fields", path="form.pdf") {"success": true, "fields": [{"name": "name", "type": "text", "value": "", "page": 0, "rect": [...]}], "message": "Found 1 form fields in form.pdf."}

await pdf_forms(operation="fill", path="form.pdf", fields={"name": "Ada"}) {"success": true, "path": ".../form_fill_....pdf", "message": "Filled 1 form fields in form.pdf, saved to form_fill_....pdf."}

await pdf_forms(operation="auto_fill", path="form.pdf", source="source.pdf") {"success": true, "path": ".../form_autofill_....pdf", "filled": 3, "missing": [], "message": "Auto-filled 3 fields in form.pdf from source.pdf."}

Inputs: path (required), operation (required), text, fields, +2 more. Returns: message, success

pdf_helpA
Read-only

List available tools and get usage help for pdf-mcp.

Return Format

A dict with keys:

  • success: bool

  • message: str - human-readable summary

  • data: list of tools with name, description, and input schema, or detailed help for a single tool when tool_name is provided.

Examples

await pdf_help() {"success": true, "message": "8 tools available.", "data": [{"name": "pdf_extract", ...}]}

await pdf_help(tool_name="pdf_extract") {"success": true, "message": "Help for pdf_extract.", "data": {...}}

Inputs: tool_name. Returns: message, success

pdf_manipulateA

Modify PDF structure and properties.

Merge, split, rotate, reorder, delete pages, compress, encrypt/decrypt, and optimize PDFs.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • merge: {path, pages}

    • split: {files: [path, ...]}

    • rotate/reorder/delete_pages/encrypt/decrypt: {path}

    • compress: {path, original_size, compressed_size}

    • optimize: {path, original_size, optimized_size} On failure: {success: False, error, error_type}.

Examples

await pdf_manipulate(operation="merge", path="a.pdf", paths=["a.pdf", "b.pdf"]) {"success": true, "path": ".../merged_....pdf", "pages": 4, "message": "Merged 2 PDFs into merged_....pdf (4 pages)."}

await pdf_manipulate(operation="rotate", path="report.pdf", angle=90) {"success": true, "path": ".../report_rotate_....pdf", "message": "Rotated report.pdf by 90 degrees, saved to report_rotate_....pdf."}

Inputs: path (required), operation (required), angle, pages, +8 more. Returns: message, success

pdf_ragC
Read-only

Build and query a RAG index over PDF content.

Chunks, indexes, and semantically searches PDF text via LanceDB. Tables are indexed as structured chunks (section='table'). Supports query-by-example and cross-document synthesis.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • chunk: {chunks, doc_id}

    • index: {chunks_indexed, doc_id}

    • search: {results: [{doc_id, chunk_id, page_num, section, source_file, text, _distance}]}

    • similar: same shape as search (seeded by a text snippet)

    • synthesize: {groups: [{doc_id, source_file, hits, snippet}], summary?}

    • list_documents: {documents: [{doc_id, chunk_count}]}

    • delete_index: {} On failure: {success: False, error, error_type}.

Examples

await pdf_rag(operation="chunk", path="book.pdf", strategy="recursive", chunk_size=1000) {"success": true, "chunks": 42, "doc_id": "a1b2c3d4e5f6", "message": "Chunked book.pdf (300 pages) into 42 chunks with recursive strategy."}

await pdf_rag(operation="search", query="quarterly revenue") {"success": true, "results": [{...}], "message": "Found 3 results for 'quarterly revenue'."}

await pdf_rag(operation="similar", text="The sky was unusually clear that night.") {"success": true, "results": [{...}], "message": "Found 2 similar passages."}

Inputs: operation (required), path, text, limit, +5 more. Returns: message, success

pdf_redactA
Destructive

Blacken sensitive content in a PDF by terms and/or PII patterns.

Return Format

A dict with keys:

  • success: bool

  • path: str - output PDF path

  • occurrences: int - number of regions redacted On failure: {success: False, error}.

Examples

await pdf_redact(path="report.pdf", pii=True) {"success": true, "path": ".../report_redact_....pdf", "occurrences": 7}

await pdf_redact(path="report.pdf", terms=["Acme Corp"]) {"success": true, "path": ".../report_redact_....pdf", "occurrences": 3}

Inputs: path (required), pii, terms, output_path. Returns: message, success

pdf_shutdownB
Destructive

Gracefully shut down the pdf-mcp server.

Return Format

A dict with keys:

  • success: bool

  • message: str - shutdown confirmation

Examples

await pdf_shutdown() {"success": true, "message": "Shutting down pdf-mcp."}

Inputs: reason. Returns: message, success

pdf_statusA
Read-only

Report server status, version, uptime, and registered tool count.

Return Format

A dict with keys:

  • success: bool

  • server: str - server name

  • version: str - server version

  • uptime_seconds: int

  • tool_count: int

  • mode: str - stdio or http

Examples

await pdf_status() {"success": true, "server": "pdf-mcp", "version": "0.1.0", "uptime_seconds": 42, "tool_count": 8, "mode": "http"}

Inputs: no named parameters. Returns: message, success

pdf_validateA
Read-only

Audit PDF quality and compliance.

PDF/A, structure, accessibility, integrity, and comparison checks.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • pdfa: {is_pdfa, details}

    • structure: {has_tags, headings, paragraphs, issues}

    • accessibility: {score (0-100), issues}

    • integrity: {intact, pages_readable, warnings}

    • compare: {same_page_count, text_similarity, diffs} On failure: {success: False, error, error_type}.

Examples

await pdf_validate(operation="accessibility", path="report.pdf") {"success": true, "score": 75, "issues": [...], "message": "Accessibility score: 75/100 for report.pdf. 0 errors, 1 warnings."}

await pdf_validate(operation="compare", path_a="a.pdf", path_b="b.pdf") {"success": true, "same_page_count": true, "text_similarity": 0.98, "diffs": [], "message": "Comparison: same page count, 98.0% text similarity between a.pdf and b.pdf."}

Inputs: path (required), operation (required), path_a, path_b. Returns: message, success

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target clearly distinct operations (extract, convert, annotate, forms, redact, classify, dedupe, validate). A few boundaries blur: pdf_analyze vs pdf_validate both perform structural audits, and pdf_export's markdown brief overlaps with pdf_convert's to_markdown and pdf_extract's text output.

    Naming Consistency4/5

    All 16 tools use a consistent pdf_ snake_case prefix with verb-style names (pdf_extract, pdf_convert, pdf_annotate, pdf_validate). Minor deviations: pdf_rag uses a noun/acronym and pdf_do is a vague verb, but the overall pattern is predictable.

    Tool Count4/5

    16 tools for a full PDF processing suite is reasonable; each operation (extract, convert, manipulate, annotate, forms, RAG, redact, classify, dedupe, validate, analyze, export) earns its place alongside help/status/shutdown infrastructure. Slightly heavy but well within scope.

    Completeness4/5

    Broad lifecycle coverage: read, transform, annotate, secure, validate, and even semantic indexing. Notable gap: pdf_analyze detects scanned PDFs but no OCR tool exists to make them usable, a common follow-on for a PDF domain. Otherwise the surface is robust with no major dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables comprehensive PDF analysis and manipulation including page size analysis, chapter extraction, splitting, compression, merging, and conversion to images. Provides both MCP server interface for AI assistants and Streamlit web interface for direct user interaction.
      -
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server for reading, rendering, and searching PDF files, specifically optimized for LLMs to extract text, tables, and technical diagrams. It enables metadata retrieval, multi-format text extraction, and page-to-image rendering using PyMuPDF.
      5
      83
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that reads PDFs and exposes them as structured Markdown, metadata, outlines, images, and tables to LLM consumers via tools like pdf_read_markdown and pdf_info.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for exporting PDF to markdown, optimized for LLM consumption.
      620 PyPI
      73
      AGPL 3.0