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. That’s what this post is about.
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.
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.
This guide shows how pdf-mcp works around those limits.
pdf-mcp is an open-source MCP server with seven tools that let Claude Code read large PDFs incrementally, solving the “PDF too large to process” error. Here’s how it works and how to set it up.
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 with Claude Code. The document wasn’t unusual. About 150 pages, 30MB. But 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 seven tools for incremental reading: inspect structure, search by keyword, read specific pages, 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–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.
The Lightbulb Moment
The architecture clicked immediately:
Instead of loading the entire PDF into context, what if Claude Code could access only the parts it actually needs?
That’s how humans 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 key insight was this: the problem isn’t PDF extraction. The problem is how the AI interacts with the document.
Building pdf-mcp meant designing for interaction patterns, not raw extraction.
Seven 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 seven small tools that mirror how humans navigate documents:
| 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_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, safe, reversible steps. The same principle applies to any MCP tool surface, as I learned when giving an AI agent full API access went wrong. Fewer focused tools always outperform a kitchen-sink approach.
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. No persistent state.
Without caching, every chat means re-extracting the entire PDF, slow and wasteful.
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 (No More Guessing)
Context overflow is the silent killer of AI workflows.
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 before breaking the session.
No more surprise truncations. No more dead conversations.
Local Files and URLs
PDFs don’t always live on disk.
Research papers, shared links, cloud-hosted docs: pdf-mcp fetches HTTP/HTTPS PDFs, caches them locally, and processes them exactly like local files.
One interface. Same behavior.
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 the three main tools (pdf_info, pdf_search, pdf_read_pages) with any PDF. 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
Since launching in January 2026, pdf-mcp has reached 7,100+ PyPI downloads across nine releases.
The tool decomposition pattern held up — and the server has evolved significantly. A few notable changes since this post was first published:
Claude Code added page-range syntax (@file.pdf:1-5) in v2.1.30 (February 2026) — useful if you already know which pages you want. But when I retested in April 2026, the syntax didn’t change how Claude Code reads large PDFs. It still doesn’t parse them natively: it probes the environment for PDF tooling (pdftotext, PyMuPDF) and shells out via Bash to whatever it finds. The 30MB / 100-page ceiling hasn’t moved. @file.pdf:N-M is a prompt hint, not a new capability.
The case for pdf-mcp is the same as it was in January: discovery across a large document — inspect the structure, search by keyword, then read only the pages that matter. When you don’t yet know which pages you want, page ranges don’t help you.
Source: Claude Code changelog
Search got smarter – and now supports hybrid mode. pdf_search started with a SQLite FTS5 index with BM25 relevance ranking and Porter stemming (v1.6.0), then added semantic search via local embeddings (v1.7.0), and now (v1.8.0) offers a mode parameter: "keyword", "semantic", or "auto". In "auto" mode, both keyword and semantic results are fused via Reciprocal Rank Fusion – useful when you want conceptual matches (“revenue growth”) alongside exact-term hits. The separate pdf_semantic_search tool was removed in v1.8.0; all search modes now go through pdf_search.
Tables are now built in. pdf_read_pages automatically returns extracted table data alongside text and images — no extra tool call needed.
pdf_extract_images was removed in v1.4.0. Images are now returned per-page in pdf_read_pages responses. If you configured pdf-mcp before March 2026, update your workflows accordingly.
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. In this case, it wasn’t reasoning or coding. It was simply reading a document. Sometimes the fix isn’t a bigger model or more context. It’s better tools.
What to read next
If pdf-mcp solved your “PDF too large” problem, you’re probably about to hit one of three 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 6,600+ installs 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.
Or go straight to the code: jztan/pdf-mcp on GitHub · pip install pdf-mcp
