Your agent doesn’t need the whole corpus. It needs the right pages.

pdf-mcp gives AI agents agentic RAG over your PDFs, one file or a whole folder: search across every document, read only the pages that matter, and get every excerpt with the page it came from. 13 tools, one MCP server.

$uv tool install pdf-mcp
Star on GitHub

Using Claude Desktop? Download the one-click extension: nothing else to install, OCR included.

2 pages read. 98.5% of its tokens never entered the context window.

Works with any MCP client

Claude CodeClaude DesktopVS CodeCursorCodex CLIKiro

try it yourself

See what your agent sees.

Drop in a PDF, paste a URL, or pick a sample. Then search it and read pages the way an agent would, and watch what each step costs.

or
100% client-side. Your PDFs never leave this tab.

Six of pdf-mcp’s tools run here in your browser with PDF.js. The JSON each returns matches the real server field for field, including the content_warning that marks extracted text as untrusted. Nothing leaves this tab.

Skim, search, then read.

Three calls replace one paste of the whole file. That is the whole idea, and it is what you just did in the demo above.

cost shown for the 216-page sample contract
1 · pdf_info~170 tokens

Learn the shape

Page count, table of contents, text coverage, and an estimated token cost before the agent commits to reading anything.

page_count: 216
total_text_chars: 344281
estimated_tokens: 172800
ocr_candidate_pages: [41, 42, 43, 131]
2 · pdf_search~230 tokens

Find the pages

Hybrid keyword and semantic ranking returns the paragraph that matched, with page and bounding box. Often enough to answer outright.

matches: p.198, p.199, p.201
total_matches: 6
search_mode: hybrid
3 · pdf_read_pages~930 tokens

Read only those

Full text, tables, and images for the two pages that matter. The other 214 stay on disk.

pages: "198,199"
from_cache: true
estimated_tokens: 925

Far more than search.

The demo shows one workflow. The same 13 tools cover the rest of what agents do with PDFs.

Hybrid search, any language

Keyword and semantic ranking fused with reciprocal rank fusion. Japanese, Chinese, and Korean get their own character-level index. pdf_search

Search a whole folder at once

Warm a directory on a time budget, get a triage card per document, then one ranked hit list across all of them with document and page on every hit. On an NVIDIA GPU the warm runs about 25x faster with optional CUDA embedding. pdf_corpus_search

Tables as rows, not soup

Structured rows with a per-table reliability flag; datasheet cells packed under a ruled header are split back into columns. pdf_read_pages

Read the chart data, not the pixels

Exact (x, y) series from a vector chart’s drawing geometry, calibrated against its tick labels. An ambiguous chart returns a render instead of a guess. pdf_extract_chart

OCR for scanned pages

Image-only pages go through Tesseract, parallelized across pages, in the language you ask for. pdf_info tells the agent which pages need it first.

Render a page for a vision model

Any page as a PNG at the DPI you choose, and any search hit or table carries a bounding box that drops straight into the render call. pdf_render_pages

Reading order that holds

Two-column papers stay in sequence instead of interleaving; vertical Japanese text reads as written. Text comes back as plain text, in order.

A cache that survives restarts

Every extraction, embedding, and render lands in a local SQLite file keyed on path and modification time. It stays until the PDF changes, so the second question about a document is free.

Fetch by URL

Hand any tool an HTTPS URL and the PDF is downloaded, validated by magic bytes, and cached. Private and local network ranges are blocked.

From a researcher using pdf-mcp

“This MCP is genuinely useful, and useful in a way that is unique because it holds through real scientific validation.”
(Markson, P 2026), on re-checking Fisher’s 1936 iris table

Why not just paste the PDF into the chat?

Most clients will take the file. What happens next is the part that goes wrong.

Pasting the PDFpdf-mcp
Context cost The whole document lands in the window. The 216-page sample contract above extracts to 344,000 characters of text, about 86,000 tokens, before the first question. The agent reads structure first, searches, then reads pages. Inspecting the sample contract, searching it, and reading the two pages that matter costs about 1,300 tokens in the demo above.
Finding the page Claude Code reads a PDF natively, but with no index it reads blind: it opens documents until the answer turns up. Measured over a folder of 120 papers, that was 187 pages read per question against 7.5 with pdf-mcp. Search names the pages before anything is read, so the range is a result rather than a guess. Every response is bounded too: lists paginate and pdf_info ships a constant-size summary by default.
Layout Two-column papers interleave, table cells arrive as runs of numbers with no column labels, and a scanned page is a blank: four pages of the sample contract have no text layer at all. Column-aware reading order out of the box, tables as rows, OCR for image-only pages, and a render when the model needs to look.
Untrusted text Extracted text carries no mark of whether a reader could see it. Across 27 real PDFs we found 19 pages of text that never shows on the page, including a white-on-white label. Hidden text is detected and flagged per page, and the info, read, search, render and corpus responses carry a content_warning so the model reads extracted text as data.
Many documents No index. On the 120-paper benchmark, the built-in tools opened 84 papers per question, across four subagents on average, to answer each one. Point it at a folder. One query returns a ranked list across every PDF, and the cache persists between sessions.

Connected in about a minute.

Install it, register it with your agent, ask about a PDF.

01

Install from PyPI.

uv tool install pdf-mcp
copy

Python 3.11 to 3.14. Or pipx install pdf-mcp. Scanned pages also need Tesseract. On Claude Desktop, skip steps 01 and 02: download pdf-mcp.mcpb and drag it onto Settings > Extensions.

02

Register it with your agent.

claude mcp add pdf-mcp -- pdf-mcp
copy

Or add the same server block to ~/.claude.json by hand.

03

Ask about a PDF.

What does the MSA in ~/contracts say about termination, and how much notice do we owe?

The agent calls pdf_info, then pdf_search, then reads the pages it needs. Point it at a folder and it uses the corpus tools instead.

Questions people ask first.

How is this different from the PDF support built into my client?

Built-in support reads the file for you, but it reads blind: nothing tells the agent which pages hold the answer, so it keeps opening pages until it finds them. On 53 questions over a folder of 120 papers, Claude Code’s built-in tools read 187 pages and took 92 seconds per question; with pdf-mcp it read 7.5 pages in 25 seconds, with the same answer quality. pdf-mcp gives the agent tools instead of a blob: it inspects the document, searches it, and reads only the pages that matched, with a persistent cache so the second conversation costs nothing to set up.

Does my document leave my machine?

Not through this server. It runs locally over STDIO and talks only to your MCP client. There is no hosted service and no telemetry. What your client then sends to its model provider is between you and that client, the same as for any tool it runs.

What about scanned PDFs and non-English documents?

pdf_info reports which pages have no text layer, and pdf_read_pages OCRs those pages with Tesseract in the language you specify. The Claude Desktop extension downloads an English Tesseract on the first scanned page; with a terminal install, install Tesseract yourself. Search works in any language; Japanese, Chinese, and Korean use a dedicated character-level index.

Is semantic search a separate service?

No. Embeddings run locally with fastembed (BAAI/bge-small-en-v1.5 by default, configurable), on CPU out of the box or on an NVIDIA GPU with the optional CUDA build of onnxruntime, about 25x faster when warming a large corpus. The first search on a document embeds its pages once and caches them; later searches reuse the cache. Setup is in the configuration guide.

Which AI clients does it work with?

Any client that speaks MCP. Claude Code, Claude Desktop, VS Code with Copilot, Codex CLI, and Kiro have step-by-step setup in the docs, and Cursor and others use the standard mcpServers block.

Give your agent the right pages.

Open source, MIT licensed, one command to install. Works with Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Kiro, and any MCP client.

The demo shows 6 of 13 tools. The server also has pdf_get_toc, pdf_read_all, pdf_render_pages, pdf_extract_chart, pdf_cache_stats, pdf_cache_clear, and server_info.

$ uv tool install pdf-mcp
copy
claude mcp add pdf-mcp -- pdf-mcp
About pdf-mcp

pdf-mcp: Agentic RAG over your PDFs, with the evidence to check every answer

pdf-mcp is an open-source MCP (Model Context Protocol) server that gives AI agents agentic RAG over your PDFs, one file or a whole folder of them. The agent decides when to search; pdf-mcp does the retrieval and hands back excerpts, each with the page it came from. When the extracted text might be wrong, the agent can render that page and check it against what’s actually printed. Hidden text, including injected instructions, is flagged, not silently passed on. It ships as a Python package and connects to Claude Desktop, Claude Code, Cursor, VS Code Copilot, Codex CLI, Kiro, and any MCP-compatible client with a single command.

What pdf-mcp solves

Large PDFs are hard for AI coding assistants to use well. Claude Code, for example, reads PDFs natively, but nothing tells it where the answer sits, so it reads until it finds it. Measured on 53 questions over a folder of 120 papers, the built-in tools read 187 pages per question and took 92 seconds; pdf-mcp read 7.5 pages in 25 seconds, and the answers were just as good. Reading pages you did not need is also wasteful: the agent spends its limited attention on pages it will never use. A folder of PDFs is harder still: with no index, the built-in tools on that benchmark opened 84 papers per question to find the ones that mattered. pdf-mcp replaces the all-at-once approach with retrieval: the agent inspects structure, searches one document or the whole folder, and reads only the pages that matter. There is no vector database to run and nothing is shipped to a hosted index; the index is a local SQLite cache, built the first time a document is read or warmed up front with pdf_corpus_warm.

How agents use pdf-mcp

The server exposes thirteen tools, but a typical workflow uses two or three. For a single document, pdf_info returns page count, table of contents, per-page text coverage, and estimated token count, so the agent knows the shape of the document before it commits to reading anything. pdf_search then runs hybrid semantic + BM25 search by default (keyword-only and semantic-only modes are one argument away) and returns structural paragraph excerpts, the bullet, paragraph, or heading that matched rather than a fixed-width window. These excerpts are often enough to answer directly. When deeper context is needed, pdf_read_pages extracts full text, images, and tables from specific pages. For a folder, pdf_corpus_warm indexes it within a time budget, pdf_corpus_overview returns a triage card per document, and pdf_corpus_search ranks matches across every document at once. Each corpus hit carries the path and title of the document it came from, so the agent can follow up with the single-document tools and hit the warm cache. The remaining seven tools (pdf_read_all, pdf_get_toc, pdf_render_pages, pdf_extract_chart, pdf_cache_stats, pdf_cache_clear, and server_info) cover full-document reads, visual inspection of scanned pages, chart-data extraction, cache management, and discovery of which optional features are installed.

What the browser demo shows

This page is a faithful in-browser simulation of six of pdf-mcp's tools, presented as a single live document view. The JSON returned by each tool matches the real server's response shape field-for-field, so developers can see exactly what the server would wire into their agent. Everything runs client-side using PDF.js: no backend, no uploads, no data leaving the tab. Features the browser cannot replicate honestly (SQLite caching, Tesseract OCR for scanned PDFs, hybrid semantic search, image extraction, structured table parsing) are stubbed with empty fields and clearly labeled as server-only. The point of the demo is to show the agent workflow, not to be a hosted PDF service.

Install

pdf-mcp is MIT-licensed and published on PyPI. Install with uv tool install pdf-mcp (or pipx install pdf-mcp), then add it to your MCP client's config; on Claude Desktop, the one-click extension needs nothing installed first. Full instructions for Claude Desktop, Claude Code, Cursor, VS Code, Codex, Kiro, and generic MCP clients are in the README. The source code is on GitHub, and the Python package is on PyPI. For a detailed write-up of the design decisions, see the blog post on how it was built.

Copied