download_pdf
Download a PDF from a URL and save it to the PDF agent home directory. Downloads to a specified subfolder (default: 'downloads') and returns the full path of the downloaded PDF.
LABSCO SUMMARY
Do not drag the PDF into the chat — that is the whole point.
Dropping a file into the conversation loads it the old way and bypasses everything here; give a path or a URL instead and the tools take over. The approach is deliberately plain — no embeddings, no chunking, no vector store — just metadata, outline, search and page ranges, which is enough for a model to navigate a thousand-page textbook by itself. Reach for page images only when text extraction is not enough, since they cost far more context than the text does.
What it is
An MCP server for selective PDF reading. Rather than loading a document whole, it lets a model check the metadata and table of contents, search the text for a pattern, and pull only the page ranges that matter — with page images available when layout or a diagram is the answer. It works on local files and on URLs, which it downloads and processes locally.
What you get
- A document's properties, page count and file information, read before anything else —
get_pdf_metadata - Bookmarks and document outline, so the model can pick a section by name instead of by guessing at page numbers —
get_pdf_outline - Text extracted from a page range such as
"5:10"or"20:", with a choice of strategy:hybridby default,nativefor clean PDFs,ocrfor scans - Pattern and regular-expression search across the document, returning context snippets around each hit, with a configurable context length and a result cap for early stopping
- Pages converted to optimised images for visual analysis, for charts, diagrams, equations and anything where the layout carries the meaning —
get_pdf_images - File paths given absolutely, or relative to
~/pdf-agent/, and online PDFs given as a URL
Requirements
No account and no key. Node.js LTS installed on the system — and in Claude Desktop specifically, "Use Built-in Node.js for MCP" must be turned off under Settings → Extensions → Advanced Settings, because the extension will not run on Claude's bundled Node. The npm package name is pdf-agent-mcp (1.0.0); install the released .dxt package by double-clicking it, or clone and build with npm install && npm run build and point your client at server/index.js.
Setup effort
One command — npx -y github:vlad-ds/pdf-agent-mcp
USE CASES
01
Answering a question from a very large document
Read the metadata and outline to locate the relevant section, then extract just that page range rather than the whole file.
02
Finding every mention of something across a report
Search with a regular expression covering the synonyms, keep enough context characters to judge each hit, and cap the results so a long document stops early.
03
Reading a chart or an equation the text does not capture
Convert the specific pages to images and let the model look at them, instead of trying to reconstruct a figure from extracted text.
04
Working with a scanned document
Switch the extraction strategy to OCR for pages where native text extraction returns nothing usable.
05
Comparing several papers at once
Run the same search terms across each document and pull only the matching sections, so a comparison does not mean loading every file.
7 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_pdf_images
Extract specific pages or page ranges from a PDF as images for visual analysis. Essential for understanding charts, diagrams, tables, figures, mathematical equations, handwritten content, or any visual elements that text extraction cannot capture. Use when you need to see the actual layout, formatting, or visual content. Supports Python-style slicing: '5' (single page), '5:10' (range), '7:' (from page 7 to end), ':5' (from start to page 5). Returns images as base64-encoded data in MCP image format. Use either absolute_path for any location or relative_path for files in ~/pdf-agent/ directory.
get_pdf_metadata
Extract metadata and basic information from a PDF file, including page count, file size, creation dates, and document properties. Use either absolute_path for any location or relative_path for files in ~/pdf-agent/ directory.
get_pdf_outline
Extract the table of contents (TOC) or outline/bookmarks structure from a PDF file. Returns hierarchical or flattened list of document sections with titles, page references, and navigation structure. Use either absolute_path for any location or relative_path for files in ~/pdf-agent/ directory.
get_pdf_text
Extract text from specific pages or page ranges of a PDF file using native text extraction. Supports Python-style slicing: '5' (single page), '5:10' (range), '7:' (from page 7 to end), ':5' (from start to page 5). Use either absolute_path for any location or relative_path for files in ~/pdf-agent/ directory. Note: Works best with PDFs containing native text; scanned PDFs may yield limited results.
search_multiple_pdfs
Search for text patterns across multiple PDF files in parallel. Processes files concurrently based on the parallelism factor for optimal performance. Increase parallelism (max: 50) to search more files simultaneously and reduce total search time. For large batches of files, prefer a single call with high parallelism rather than multiple smaller calls (e.g., search 100 files with parallelism=50 in one call instead of multiple calls with 20 files each). Returns matches and errors for each file separately.
search_pdf
Search for text patterns (including regex) within a PDF file and return matching pages with context snippets. Supports Python-style page ranges and early stopping for performance. Use /pattern/flags format for regex (e.g., '/budget|forecast/gi') or plain text for literal search.
BEFORE YOU INSTALL
What to know first
Tools you get
7 tools when we connected.
Requires
npx on PATH
CONTEXT COST
Light Standing cost
Rated by the size of the 7 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"pdf-agent-mcp": {
"command": "npx",
"args": [
"-y",
"github:vlad-ds/pdf-agent-mcp"
]
}
}
}npx
TERMINAL
npx -y github:vlad-ds/pdf-agent-mcp
