pdf-mcp

Surgical PDF access for AI agents: search, read, and extract without flooding context.

An MCP server that lets Claude Code and other AI agents search a PDF by meaning or keyword, read only the pages that matter, and cleanly pull out tables, images, and scanned text, even from multi-column and Japanese layouts.

mcp-name: io.github.jztan/pdf-mcp

Try it in your browser

See what your AI agent sees →

Drop in any PDF, or a whole folder of them, and watch an agent triage the corpus, search across every document at once, and read only the pages that matter, using a fraction of the tokens. 100% client-side, no install required.

Why pdf-mcp?

Without pdf-mcp With pdf-mcp

Large PDFs Context overflow Chunked reading

Token budgeting Guess and overflow Estimated tokens before reading

Finding content Load everything Hybrid search (BM25 keyword + semantic)

Tables Lost in raw text Extracted and inlined per page

Charts Trapped in the plot image Extracted as (x, y) data tables

Multi-column PDFs Columns interleaved in extracted text Column-aware reading order, built in

Vertical scripts (Japanese) Columns scrambled / glyph soup Geometric reorder of vertical text (tategaki / 縦書き); CJK keyword search works on unspaced Japanese/Chinese/Korean text via a char-split FTS index

Images Ignored Extracted as PNG files

Repeated access Re-parse every time SQLite cache

Scanned PDFs No text extracted OCR via Tesseract, parallelized across pages (pdf_read_pages(ocr=True))

Visual content Must describe in words Render page as image (pdf_render_pages)

Hidden / injected text Silently ingested as if a human vetted it Flagged as untrusted: hidden-text detection (content_trust=True)

Folders of PDFs One document at a time Corpus tools: warm, triage, and search across a whole folder

Tool design Single monolithic tool 13 specialized tools

Features

• Hybrid search: find relevant pages with a question, not a page range. Combines BM25 keyword and semantic search via Reciprocal Rank Fusion

• Corpus search: point the server at a folder of PDFs: warm them into the cache, get per-document triage cards, and search across all documents at once with ranked, document-attributed hits

• Paginated reading: fetch only the pages your agent needs; large documents don't blow your context window

• OCR: scanned and image-based PDFs are fully readable and searchable via Tesseract, parallelized across pages for ~2–3x faster extraction on typical scans

• Structured extraction: tables, embedded images, and table of contents returned as structured data, not text soup

• Chart data extraction: pull exact (x, y) tables from vector charts, read from the plot geometry rather than guessed from the image; declines with a rendered image when a chart can't be read reliably

• Vertical-script reading order: Japanese tategaki (縦書き) reconstructed from glyph geometry into correct top-to-bottom, right-to-left order; article segmentation for dense magazine layouts; mojibake filtered

• Persistent cache: SQLite-backed; re-reads are instant and survive server restarts

• Secure URL fetching: HTTPS-only with SSRF protection; local network ranges are blocked

• Content-trust / hidden-text detection: flags text a human reader can't see (invisible render mode, sub-point fonts, transparent or white-on-white fill, off-page) so an agent treats it as untrusted rather than vetted. Flag-only: nothing is stripped

Contents

• Installation

• Quick Start

• Tools

• Example Workflow

• Remote / HTTP transport

• Configuration

• Roadmap

• Contributing

• Contributors

• Security

• License

Installation

pip install pdf-mcp

Semantic search is included by default (hybrid auto search is built on it; ~67 MB embedding model download on first use). The former [semantic] and [cjk] extras remain as no-op aliases. Platform note: the bundled onnxruntime has no wheels for Intel macOS on Python 3.14+ or Alpine/musl; use Python ≤ 3.13 there.

Correct reading order on multi-column PDFs is built in and needs no extra. The former [multicolumn] extra remains as a no-op alias, so existing install instructions keep working.

Japanese/Chinese/Korean PDFs work out of the box: keyword search uses a char-split FTS index that matches unspaced CJK terms, and semantic CJK search is covered by the default install.

For OCR on scanned PDFs (requires system Tesseract):

# macOS
brew install tesseract

# Ubuntu/Debian
apt install tesseract-ocr

# On Windows, download the installer from:
# https://github.com/UB-Mannheim/tesseract/wiki
# Then add the install directory to your PATH.

Quick Start

Choose your MCP client below to get started:

claude mcp add pdf-mcp -- pdf-mcp

Or add to ~/.claude.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after updating the config.

Requires VS Code 1.101+ with GitHub Copilot.

CLI:

code --add-mcp '{"name":"pdf-mcp","command":"pdf-mcp"}'

Command Palette:

• Open Command Palette (Cmd/Ctrl+Shift+P)

• Run MCP: Open User Configuration (global) or MCP: Open Workspace Folder Configuration (project-specific)

• Add the configuration:

{
  "servers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

• Save. VS Code will automatically load the server.

Manual: Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

codex mcp add pdf-mcp -- pdf-mcp

Or configure manually in ~/.codex/config.toml:

[mcp_servers.pdf-mcp]
command = "pdf-mcp"

Create or edit .kiro/settings/mcp.json in your workspace:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp",
      "args": [],
      "disabled": false
    }
  }
}

Save and restart Kiro.

Most MCP clients use a standard configuration format:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

With uvx (for isolated environments):

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "uvx",
      "args": ["pdf-mcp"]
    }
  }
}

Verify Installation

pdf-mcp --help

Tools

The typical pattern: call pdf_info first to plan, then pdf_search to locate; its paragraph excerpts are often enough to answer directly. Use pdf_read_pages or pdf_read_all when you need deeper context. For a folder of PDFs, start with pdf_corpus_overview to triage, then pdf_corpus_search to search across documents.

Tool What it does

pdf_info Page count, metadata, TOC summary, scanned-page detection. Call first. Pass content_trust=True for a content_trust block (suspicious, hidden_text_runs, hidden_chars, injection_in_hidden, pages_flagged, signals); add detail=True for per-span spans.

pdf_get_toc Full table of contents for documents with >50 bookmarks

pdf_corpus_warm Warm a folder (or list) of PDFs into the cache, text and optional embeddings, within a time budget. Returns per-doc status plus unprocessed/skipped.

pdf_corpus_overview Per-document triage cards for a folder: title, page count, top TOC entries, text coverage. Auto-warms within the budget.

pdf_corpus_search Search across a folder of PDFs (keyword, semantic, or hybrid), returning ranked hits with document and page provenance, excerpts, and coverage.

pdf_read_pages Read specific pages or ranges; OCR-on-demand; embedded images + tables, each with source bbox + clip coordinates. Always returns hidden_text_detected (response level) and per-page hidden_text; `hidden_text_detected: