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, then read only the pages that matter. 13 tools, one MCP server.

$pip install pdf-mcp
Star on GitHub

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. 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.

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 is about 86,000 tokens of extracted text 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.
Finding the page Claude Code reads a PDF natively, but in windows of up to 20 pages per call, with no way to know which window holds the answer. Other clients silently truncate. 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, tables flatten into word soup, and a scanned page is a blank. 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 A PDF’s text, including white-on-white instructions, arrives as prose indistinguishable from yours. Hidden text is detected and flagged, and every response carries a content_warning so the model reads extracted text as data.
Many documents One file at a time, re-uploaded every conversation. 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.

pip install pdf-mcp
copy

Python 3.10+. Add pdf-mcp[ocr] for scanned pages (needs Tesseract). Column-aware reading order is built in.

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: Claude Code takes a page range and returns up to 20 pages a call, so a 216-page contract is eleven guesses unless something narrows the range first. 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. With the [ocr] extra and Tesseract installed, pdf_read_pages OCRs those pages in the language you specify. 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.

Read the docs GitHub PyPI Blog
$ pip install pdf-mcp
copy
claude mcp add pdf-mcp -- pdf-mcp
About pdf-mcp

pdf-mcp: Agentic RAG over your PDFs, one file or a whole folder

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 rather than whole documents. 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, now reads PDFs natively, but a read returns a window of up to 20 pages, so a 300-page standard is fifteen blind reads when you do not already know where the answer sits. 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, because there is no native way to ask which of forty documents even mentions the thing you are looking for. 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 pip install pdf-mcp, then add it to your MCP client's config. 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