How many pages can Claude read?
Claude can read up to 100 pages per PDF for visual analysis, with a 30MB file size limit. Files that exceed either limit trigger a “PDF too large to process” error. In Claude Code, you’ll also hit practical issues on PDFs as small as 5MB when the extracted text overflows the context window.
These are hard limits. They don’t change based on your plan or Claude Code version. To read larger PDFs, you need a tool that breaks the document into pieces Claude can handle.
How many PDFs can you upload to Claude at once?
Claude.ai supports multiple file attachments per message, with each file subject to the 30MB / 100-page limit. Claude Code has no fixed file count, but every PDF still has to fit through the same per-file ceiling.
If you’re working with a folder of PDFs, the bottleneck isn’t usually the number of files. It’s that even one large file blocks the whole batch. pdf-mcp solves this by reading each PDF incrementally instead of loading the full document into context. Since v2.0.0 its corpus tools also search across the whole folder, up to 100 PDFs in a single call. For the full folder-to-knowledge-base workflow, see Turn a Folder of PDFs Into an AI Agent Knowledge Base.
What does “too many pages in document” mean in Claude?
“Too many pages in document” is Claude’s page-count error, separate from the 30MB file-size error. It triggers when a PDF exceeds 100 pages for visual analysis, regardless of file size. A 20MB, 200-page PDF will fail with this error even though it’s well under the size cap.
The two limits get conflated because they often trip together, but they’re independent:
- File-size error (“PDF too large to process”): PDF exceeds 30MB
- Page-count error (“too many pages in document”): PDF exceeds 100 pages
A 150-page, 25MB PDF passes the size check and fails the page check. Splitting it manually works once, but breaks down for any workflow that needs to query across the full document.
pdf-mcp’s pdf_read_pages tool sidesteps this by reading page ranges on demand. You never load all 200 pages at once, so the 100-page ceiling never applies. For larger documents where you don’t yet know which pages matter, pdf_search finds the relevant ranges first. A section-chunking approach goes further by reading logical units (chapters, subsections) instead of fixed page ranges, which cuts tool calls by roughly 9 per query on documents with clean TOCs.
pdf-mcp is an open-source MCP server with 13 tools that let Claude Code read large PDFs incrementally, solving the “PDF too large to process” error.
Claude Code can write complex code and debug distributed systems, but give it a 30MB PDF and it fails with “PDF too large to process.”
I hit this while trying to analyze a technical standard: about 150 pages, 30MB, nothing unusual about it. Claude Code simply refused to read it.
If you work with specs, standards, contracts, or long technical PDFs, you’ve probably seen this too. It’s not just Claude. Most AI coding assistants struggle with large documents.
So I did what any developer does next: I went looking for an existing solution.
TL;DR: Claude Code fails on large PDFs because it loads the entire document into context at once. pdf-mcp is an open-source MCP server that fixes this with 13 tools for incremental reading: inspect structure, search by keyword, read specific pages, search across whole folders, and cache results across sessions. It handles local files and URLs without hitting context limits.
Install:
pip install pdf-mcp && claude mcp add pdf-mcp -- pdf-mcp
The search for existing solutions
I found a few MCP servers claiming to handle PDFs.
- Some were abandoned. Installation failed, dependencies were broken, issues sat unanswered for months.
- Some worked, but poorly. They dumped the entire PDF into context in one shot. You still hit limits, just with extra steps. None of them cached results, so every new conversation re-extracted everything from scratch.
- RAG felt like overkill. Vector databases, embeddings, chunking strategies, for simply reading a PDF? The complexity didn’t match the problem.
I’d already built a few MCP servers before: redmine-mcp-server for project management integration and qt4-doc-mcp-server for Qt documentation. I knew the protocol, and I knew what good tool design looked like.
That frustration, combined with that experience, became pdf-mcp.
Why Claude Code says “PDF too large to process”
Claude Code’s PDF handling has real constraints:
- Practical limits on how much text it can load from a file at once
- Practical issues with documents over ~100 pages
- “PDF too large” errors on files as small as 5MB
It’s not just file size. It’s how much text gets extracted.
Typical problem documents:
- Industry standards (ISO, IEEE): hundreds of pages, often 40 to 80MB
- SDK and API docs: dense text, long appendices
- Financial and research reports with tables and figures
When you hit the limit, it’s not a polite failure. The server can get blocked, forcing you to start a fresh conversation, all context gone.
Even when PDFs do load, dumping 100 pages into the context window is wasteful. You burn tokens on content you don’t need, leaving less room for actual reasoning.
Read the way people read
Instead of loading the entire PDF into context, what if Claude Code could access only the parts it actually needs?
That’s how people read long documents. We:
- Check the table of contents
- Search for relevant sections
- Read specific pages
- Jump around as needed
AI shouldn’t be any different.
Designing for how AI actually works
The problem isn’t PDF extraction. It’s how the AI interacts with the document, so building pdf-mcp meant designing for interaction patterns rather than for raw extraction.
Thirteen tools, not one
The existing MCP tools I found all made the same mistake: a single monolithic function that dumps everything at once.
Instead of exposing one large “read_pdf” function, I broke the interface into small single-purpose tools that mirror how humans navigate documents (nine at launch, 13 as of v2.0.0):
| Tool | Purpose |
|---|---|
pdf_info |
Inspect metadata and page count |
pdf_get_toc |
Extract table of contents |
pdf_search |
Locate relevant pages |
pdf_read_pages |
Read specific page ranges (images and tables included) |
pdf_read_all |
Full document read (with safety limits) |
pdf_render_pages |
Render a page as an image |
pdf_extract_chart |
Read exact data tables out of vector charts |
pdf_corpus_warm |
Pre-extract a folder of PDFs on a time budget |
pdf_corpus_overview |
Triage card per document: title, pages, TOC, coverage |
pdf_corpus_search |
One query across the whole folder, ranked hits with provenance |
server_info |
Check server capabilities |
pdf_cache_stats |
Inspect cache performance |
pdf_cache_clear |
Cache maintenance |
This turns PDF reading from a single high-risk operation into a sequence of small steps you can back out of. The same principle applies to any MCP tool surface, as I learned when giving an AI agent full API access went wrong. On a surface like this one, a few focused tools beat a kitchen-sink function.
Each step also needs to fail gracefully. When pdf_search hits a corrupted page or pdf_read_pages gets an out-of-range request, the tool returns structured errors rather than crashing the session. For the broader patterns behind this (circuit breakers, validation gates, structured fallbacks), see AI Agent Error Handling Patterns.
A typical workflow looks like this:
pdf_info→ “This is a 150-page document”pdf_get_toc→ “Section 4 covers revenue”pdf_search("revenue by region")→ “Pages 45-52”pdf_read_pages(45, 52)
Instead of flooding the context with 150 pages, Claude Code works with just 8. That leaves room to actually reason.
Solving the caching problem
MCP servers using STDIO transport spawn a new process per conversation, so nothing persists between them. Without caching, every chat re-extracts the entire PDF.
pdf-mcp uses SQLite caching:
- Extracted text, metadata, and images persist to
~/.cache/pdf-mcp/cache.db - Cache invalidation via file modification time
- 24-hour TTL (configurable with
PDF_MCP_CACHE_TTL)
The first conversation performs extraction. Every conversation after that reads from cache and returns instantly.
Token estimation before the request
Context overflow is easy to miss until the session is already broken.
pdf-mcp estimates token usage for extracted text. Before Claude Code requests 50 pages, it can check whether they’ll fit and narrow the request instead of truncating the answer or killing the conversation.
Local files and URLs
PDFs don’t always live on disk. For research papers, shared links, and cloud-hosted docs, pdf-mcp fetches HTTP/HTTPS PDFs, caches them locally, and processes them through the same interface as local files.
The build
Two libraries made this straightforward:
- FastMCP removed protocol plumbing, letting me focus on tool ergonomics
- PyMuPDF (fitz) handled fast, reliable text and image extraction
The hardest part was testing. PDFs are chaotic: scans, broken encodings, corrupted files, password protection. I built a test corpus of pathological PDFs and made sure failures were graceful, not catastrophic. For a broader framework on testing non-deterministic AI systems, see Testing AI Agents in Production.
pdf-mcp is open source on GitHub and published on PyPI. Releases are automated via GitHub Actions: tag it, test it, ship it. After shipping, I ran a full security audit and found 8 vulnerabilities including SSRF, prompt injection, and path traversal.
Try it yourself
See what your AI agent sees. The live demo lets you walk through six of the tools with any PDF: pdf_info, pdf_search, and pdf_read_pages on a single document, plus the corpus flow over a bundled 6-PDF sample corpus or a folder of your own. 100% client-side, no install required. → pdf-mcp.jztan.com
pdf-mcp is also available on PyPI to self-host. Install and add to your Claude Code setup:
pip install pdf-mcp
claude mcp add pdf-mcp -- pdf-mcp
Or for Claude Desktop:
pip install pdf-mcp
Then add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}
Restart Claude Desktop after saving the config.
Then ask Claude to analyze any PDF, local or remote, 5 pages or 500.
Source: https://github.com/jztan/pdf-mcp
Since launch
pdf-mcp has shipped roughly a release a week since launching in January 2026, and has passed 39,000 PyPI downloads. The tool decomposition pattern held up, and I later distilled the full set of lessons that survived production into five patterns for how agents should read PDFs. Rather than replay the changelog, this is what the tool grew into:
- Search got layered. Linear page scans became SQLite FTS5 keyword search with BM25 ranking, then local semantic embeddings, then a hybrid mode that fuses both with Reciprocal Rank Fusion (when each wins). Excerpts now return the whole matching paragraph, and since v2.0, one query can rank hits across an entire folder of PDFs.
- Hard layouts read in order. Column-aware extraction keeps multi-column PDFs in reading order, vertical Japanese (tategaki) documents extract in sequence, and parallel OCR handles scanned pages ~2-3x faster than at launch.
- Charts became data. Vector charts return exact
(x, y)tables read from the drawing geometry; unclear charts decline with a rendered image instead of a guess. - An LLM guards the releases. Alongside the unit tests, LLM-driven QA exercises the tools the way an agent would, and has caught search regressions the test suite missed.
For version-by-version specifics, see the CHANGELOG.
One question I still get: doesn’t Claude Code’s page-range syntax (@file.pdf:1-5, added in v2.1.30, February 2026) already solve this? It helps when you already know which pages you want, but it never moved the ceiling. Claude Code still doesn’t parse PDFs natively: it probes the environment for tooling (pdftotext, PyMuPDF) and shells out via Bash, so the 30MB / 100-page limit is unchanged. The case for pdf-mcp is the same as in January: discovery across a large document, where page ranges don’t help because you don’t yet know which pages matter. (Source: Claude Code changelog.)
The core design principle hasn’t changed: inspect, search, read only what you need. The tools have just gotten faster and more capable.
AI tools fail in surprisingly ordinary places. This one wasn’t reasoning or coding, it was reading a document, and the fix was a better tool rather than a bigger model.
What to read next
If pdf-mcp solved your “PDF too large” problem, you’re probably about to hit one of four follow-on questions. Here’s where each goes:
“How does Claude Code actually decide which tool to call?” → How Claude Code Actually Reads PDFs: Lessons from Building an MCP Server The scout-then-read pattern wasn’t something I designed for. Agents discovered it on their own. This post walks through the behavior I observed across 39,000+ downloads and what it means for how you design tools.
“I want to build my own MCP server for [my domain].” → How to Build an MCP Server in Python with FastMCP 3.0 The step-by-step version. FastMCP 3.0, tool decomposition, and the design patterns from pdf-mcp adapted into a template you can fork.
“Should I use semantic search or keyword search for my agent?” → Semantic vs Keyword Search for AI Agents: When to Use Each pdf-mcp started with linear page scans, moved to FTS5 + BM25, then added semantic embeddings, and now offers hybrid search via Reciprocal Rank Fusion. Here’s the decision framework behind each step, and when you’d want just one or the other.
“How should I chunk PDFs for my agent’s retrieval?” → Section Chunking vs Page Chunking for AI Agents Pages are the unit the file format gives you, not the unit retrieval should respect. The benchmark on three arxiv PDFs (GPT-3, an LLM survey, a GNN review) and the named pattern (“Page-Walk Trap”) behind this decision.
FAQ: Claude and Large PDFs
Limits below are what Anthropic’s docs say as of 2 August 2026. They move, so check the PDF support page and the file upload help article before you plan around them.
Can Claude read PDFs?
Yes. Claude reads PDFs on claude.ai and through the Anthropic API. It extracts the text and also reads visual content like charts and tables. On claude.ai, that visual analysis covers PDFs of 100 pages or fewer. From 101 to 1,000 pages, Claude reads text only.
Reading and finding are different problems. When the answer sits on 6 pages out of 300, the work is in locating those 6. I watched agents settle into the same scouting habit across pdf-mcp’s install base, which I wrote up in how Claude Code actually decides which PDF tool to call.
How many PDFs can I upload to Claude?
Claude.ai accepts up to 20 files per chat at 500MB per file, and caps PDFs at 1,000 pages. Projects use the same per-file ceiling and set no fixed file count, so the context window becomes the real limit.
The file count is rarely what stops you. One long document eats the context the rest of the batch needs, and you are back to splitting files by hand. pdf-mcp reads each PDF incrementally, and its corpus tools query up to 100 PDFs in a single call.
How do I process a PDF over 100 pages with the Anthropic API?
The API allows 600 pages per request, or 100 when the request’s context window is under 1M tokens, inside a 32MB maximum request size. Both limits apply to the whole request payload, not just the PDF.
Past that, split the document or upload it with the Files API and reference it by file_id to keep the payload small. Better still, stop sending whole documents: search first, then read only the ranges that matched. That ordering is one of five patterns for how agents should read PDFs.
Or go straight to the code: jztan/pdf-mcp on GitHub · pip install pdf-mcp
