# pdf-mcp

Gives your agent access to one PDF or a whole folder: hybrid search, reading only the pages that matter, tables and OCR.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 155
- Author: jztan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/jztan/pdf-mcp
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/mcp/pdf-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PDF_MCP_CACHE_DIR`, `PDF_MCP_CACHE_TTL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mcp
```
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>

### Codex

**Platform CLI**
```bash
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-mcp
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
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>

## When to use it
- 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
- 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.pdf` as rows

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md