PDF RAG MCP Server

MCP server for RAG over messy PDFs — extract, chunk, embed, and search scanned, multi-column, and table-heavy documents.

![Python 3.12+](https://www.python.org/downloads/) ![License: MIT](LICENSE) ![MCP](https://modelcontextprotocol.io)

---

<img src="docs/images/inspector-tools.png" alt="MCP Inspector — Tools" width="800"/> All 6 tools running in the MCP Inspector

What is RAG?

RAG (Retrieval-Augmented Generation) is a technique that makes AI assistants smarter by giving them access to your own documents. Instead of relying only on training data, the AI first retrieves relevant chunks from your files, then uses them as context to generate accurate, grounded answers.

Traditional AI:  User Question → LLM → Answer (may hallucinate)
RAG:             User Question → Search Your Docs → LLM + Context → Accurate Answer

This MCP server is the "Search Your Docs" part — it ingests PDFs, breaks them into searchable chunks, and lets any MCP-compatible AI assistant find the right information instantly.

Why This Server?

Most PDF tools choke on real-world documents — scanned pages, multi-column layouts, embedded tables. This MCP server handles them all:

Scanned PDFs — Automatic OCR via Tesseract when text extraction fails
Multi-column layouts — Layout-preserving block sorting with PyMuPDF
Tables — Detected and extracted as clean markdown via pdfplumber
Semantic search — Find information by meaning, not just keywords
100% local — Embeddings run on your machine. No data leaves your system.

Demo

Ingest a PDF and search it

<img src="docs/images/inspector-ingest.png" alt="PDF Ingest" width="800"/> Ingesting a PDF — extracts text, chunks it, generates embeddings

<img src="docs/images/inspector-search.png" alt="Semantic Search" width="800"/> Semantic search returns ranked results with page numbers and similarity scores

Tool Examples

1. Ingest a PDF

Tool: pdf_ingest
Input: { "file_path": "/home/user/reports/ai-healthcare-2026.pdf" }

{
  "doc_id": "a1b2c3d4e5f6",
  "filename": "ai-healthcare-2026.pdf",
  "total_pages": 4,
  "total_chunks": 12,
  "scanned_pages": [],
  "status": "ingested"
}

2. Search across documents

Tool: pdf_search
Input: { "query": "drug discovery timelines", "limit": 3 }

{
  "query": "drug discovery timelines",
  "total_results": 3,
  "results": [
    {
      "text": "Drug discovery timelines shortened by 30% using generative AI models...",
      "score": 0.8742,
      "page_num": 1,
      "source_filename": "ai-healthcare-2026.pdf"
    },
    {
      "text": "The healthcare AI market is experiencing rapid growth... Drug Discovery 8.7B...",
      "score": 0.6521,
      "page_num": 3,
      "source_filename": "ai-healthcare-2026.pdf"
    }
  ]
}

3. Extract tables as markdown

Tool: pdf_extract_tables
Input: { "file_path": "/home/user/reports/ai-healthcare-2026.pdf", "page_num": 3 }

{
  "page_num": 3,
  "tables_found": 1,
  "markdown": "| Application | Market 2025 | Market 2030 |\n|---|---|---|\n| Diagnostic Imaging | $12.4B | $45.2B |\n| Drug Discovery | $8.7B | $32.1B |"
}

4. Get a specific page

Tool: pdf_get_page
Input: { "doc_id": "a1b2c3d4e5f6", "page_num": 1 }

{
  "doc_id": "a1b2c3d4e5f6",
  "page_num": 1,
  "text": "Artificial Intelligence in Healthcare\nA Comprehensive Report - 2026\n\nExecutive Summary\nArtificial intelligence is transforming healthcare delivery..."
}

5. List & manage documents

Tool: pdf_list_documents

{
  "total_documents": 2,
  "documents": [
    { "doc_id": "a1b2c3d4e5f6", "source_filename": "ai-healthcare-2026.pdf", "total_chunks": 12, "total_pages": 4 },
    { "doc_id": "f6e5d4c3b2a1", "source_filename": "quarterly-report.pdf", "total_chunks": 45, "total_pages": 18 }
  ]
}

Tool: pdf_delete
Input: { "doc_id": "f6e5d4c3b2a1" }
→ { "doc_id": "f6e5d4c3b2a1", "chunks_deleted": 45, "status": "deleted" }

MCP Tools

| Tool | Description | |------|-------------| | pdf_ingest | Ingest a PDF: extract text (with OCR fallback), chunk, embed, and store | | pdf_search | Semantic search across all ingested PDFs with similarity scores | | pdf_get_page | Get full extracted text for a specific page | | pdf_list_documents | List all ingested documents with metadata | | pdf_delete | Remove a document and its embeddings from the store | | pdf_extract_tables | Extract tables from a page as markdown |

Installation

Prerequisites

Python 3.12+
Tesseract OCR (for scanned PDF support)

# Ubuntu/Debian
sudo apt install tesseract-ocr

# macOS
brew install tesseract

Install from source

git clone https://github.com/MBaranekTech/pdf-rag-mcp.git
cd pdf-rag-mcp
uv venv .venv && source .venv/bin/activate
uv pip install -e .

Install from PyPI

pip install pdf-rag-mcp

Configuration

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "pdf-rag": {
      "command": "/path/to/pdf-rag-mcp/.venv/bin/pdf-rag-mcp"
    }
  }
}

Claude Code

claude mcp add pdf-rag -- /path/to/pdf-rag-mcp/.venv/bin/pdf-rag-mcp

Cursor / VS Code

Add to .cursor/mcp.json or VS Code MCP settings:

{
  "mcpServers": {
    "pdf-rag": {
      "command": "/path/to/pdf-rag-mcp/.venv/bin/pdf-rag-mcp"
    }
  }
}

Docker

docker build -t pdf-rag-mcp .
docker run -v /path/to/pdfs:/pdfs pdf-rag-mcp

Architecture

PDF File
  │
  ▼
┌─────────────────────────────────────────┐
│  pdf_extractor.py                       │
│  ┌───────────┐   ┌──────────────────┐   │
│  │  PyMuPDF  │──▶│ Text extraction  │   │
│  └───────────┘   │ (layout-aware)   │   │
│  ┌───────────┐   ├──────────────────┤   │
│  │ Tesseract │──▶│ OCR fallback     │   │
│  └───────────┘   │ (scanned pages)  │   │
│  ┌───────────┐   ├──────────────────┤   │
│  │pdfplumber │──▶│ Table detection  │   │
│  └───────────┘   └──────────────────┘   │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  chunker.py                             │
│  Split into ~500-word overlapping       │
│  chunks with page number metadata       │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  vector_store.py                        │
│  ┌────────────────────┐  ┌───────────┐  │
│  │ sentence-transformers│  │ ChromaDB  │  │
│  │ (all-MiniLM-L6-v2) │─▶│ (cosine)  │  │
│  └────────────────────┘  └───────────┘  │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  server.py (FastMCP)                    │
│  6 tools exposed via MCP protocol       │
└─────────────────────────────────────────┘

How It Works

Ingest — PyMuPDF extracts text blocks sorted by position. Pages with < 50 characters of text are automatically OCR'd via Tesseract.
Chunk — Text is split into ~500-word overlapping chunks (50-word overlap), preserving page number metadata.
Embed — Chunks are embedded using all-MiniLM-L6-v2 (~80MB, runs locally, no API keys).
Store — Embeddings and metadata are persisted in ChromaDB at ~/.pdf-rag-mcp/chroma_db/.
Search — Queries are embedded and matched against stored chunks using cosine similarity.

Development

# Setup
uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Test with MCP Inspector (requires Node.js)
fastmcp dev inspector src/pdf_rag_mcp/server.py:mcp --with-editable .
# Opens browser UI at http://localhost:6274

Tech Stack

| Component | Technology | |-----------|-----------| | MCP Framework | FastMCP | | PDF Extraction | PyMuPDF | | Table Extraction | pdfplumber | | OCR | Tesseract via pytesseract | | Embeddings | sentence-transformers (all-MiniLM-L6-v2) | | Vector Store | ChromaDB |

Privacy

All processing happens locally:

Embedding model runs on your machine
PDF content is never sent to external APIs
Data stored at ~/.pdf-rag-mcp/chroma_db/

License

MIT

PDF RAG MCP Server