pdf-mcp — Claude Code MCP server: search PDFs and folders
Gives your agent access to one PDF or a whole folder: hybrid search, reading only the pages that matter, tables and OCR.
claude mcp add --env PDF_MCP_CACHE_DIR=<PDF_MCP_CACHE_DIR> --env PDF_MCP_CACHE_TTL=<PDF_MCP_CACHE_TTL> --transport stdio pdf-mcp -- uvx pdf-mcpWhat pdf-mcp does
pdf-mcp is an MCP server that turns PDFs into a source your agent can query. The agent decides when to search; the server runs the retrieval and returns excerpts. It handles a single file or an entire folder: warm the corpus into cache, triage the documents, then search across all of them at once.
Inside are 13 separate tools instead of one big one. pdf_info reports page count, metadata, a table of contents summary and flags scanned pages. pdf_search runs keyword plus semantic search and returns a paragraph or a context window with source coordinates. pdf_read_pages reads specific pages, with OCR on demand, tables and embedded images. For folders there are pdf_corpus_overview and pdf_corpus_search. Pages can be rendered to PNG for vision models, and chart data comes back as (x, y) tables. Results sit in a SQLite cache that survives restarts.
You need Python 3.10 or later, and the pdf-mcp command installs through uv or pipx. OCR on scanned pages needs Tesseract installed separately; without it recognition will not run. Non-English documents need language configuration, covered in the docs. CUDA embedding works only on NVIDIA cards.
What it helps with
- find the right passage in a long PDF without loading the whole file
- read only the pages that hold the answer
- pull a table or chart data out of a document
- recognize text in scanned pages with OCR
- search a folder of PDFs with document and page provenance
Example prompts for the agent
- Use pdf-mcp to summarize
report.pdf - Search this folder of PDFs for anything about payment terms and show the pages
- Extract the table from
invoice.pdfas rows
How to install pdf-mcp
Platform CLI
claude mcp add --env PDF_MCP_CACHE_DIR=<PDF_MCP_CACHE_DIR> --env PDF_MCP_CACHE_TTL=<PDF_MCP_CACHE_TTL> --transport stdio pdf-mcp -- uvx pdf-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pdf-mcp <command>
Platform CLI
codex mcp add pdf-mcp --env PDF_MCP_CACHE_DIR=<PDF_MCP_CACHE_DIR> --env PDF_MCP_CACHE_TTL=<PDF_MCP_CACHE_TTL> -- uvx pdf-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pdf-mcp <command>
Config file
{
"mcpServers": {
"pdf-mcp": {
"command": "uvx",
"args": [
"pdf-mcp"
],
"env": {
"PDF_MCP_CACHE_DIR": "<PDF_MCP_CACHE_DIR>",
"PDF_MCP_CACHE_TTL": "<PDF_MCP_CACHE_TTL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pdf-mcp <command>
Config file
{
"servers": {
"pdf-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"pdf-mcp"
],
"env": {
"PDF_MCP_CACHE_DIR": "<PDF_MCP_CACHE_DIR>",
"PDF_MCP_CACHE_TTL": "<PDF_MCP_CACHE_TTL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pdf-mcp <command>
Platform CLI
gemini mcp add -e PDF_MCP_CACHE_DIR=<PDF_MCP_CACHE_DIR> -e PDF_MCP_CACHE_TTL=<PDF_MCP_CACHE_TTL> pdf-mcp uvx pdf-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pdf-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about pdf-mcp
How do I install pdf-mcp in Claude Code?
Install the command first: uv tool install pdf-mcp or pipx install pdf-mcp. Then add the server: claude mcp add pdf-mcp -- uvx pdf-mcp.
What does pdf-mcp do?
It is an MCP server for searching and reading PDFs. Your agent searches by meaning or keyword, reads only the pages it needs, and pulls out tables, images and scanned text.
What does pdf-mcp need to run?
Python 3.10 or later. OCR on scanned pages also needs Tesseract installed, otherwise recognition will not run.
