MC
Search

MCP Server for Local PDF Text Search

Search local PDFs with an MCP server to read and find text quickly and securely on your system.

View on GitHub
Quick Install
npx -y @gpetraroli/mcp_pdf_reader

Overview

This MCP (Model Context Protocol) server lets you index and search text inside local PDF files, exposing the functionality as discoverable tools that other apps or LLM agents can call. It keeps your documents and search index on your own machine, so sensitive content never leaves your environment while still providing fast, contextual search over PDF content.

The server is intended for developers who want to integrate PDF text search into local automation, chat agents, or data pipelines. It runs as a small HTTP-based MCP server, provides document ingestion and vector search, and returns text snippets and page references so calling programs can present or act on the results.

Features

  • Local-only PDF ingestion and indexing (no cloud uploads required)
  • Full-text extraction and chunking for long documents
  • Vector-based semantic search plus keyword fallback
  • Tool endpoints exposed via MCP for discovery and invocation
  • Configurable chunk size, overlap and search result count
  • Lightweight server intended for developer integration and automation

Installation / Configuration

Prerequisites: Python 3.8+ and git. Example steps below assume a Unix-like shell.

Clone the repo and create a virtual environment:

git clone https://github.com/gpetraroli/mcp_pdf_reader.git
cd mcp_pdf_reader
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Basic environment variables (examples and sensible defaults):

# .env or export in shell
MCP_HOST=127.0.0.1      # host to bind to
MCP_PORT=3333           # HTTP port for the MCP server
PDF_DIR=./pdfs          # directory with PDF files to index
INDEX_DIR=./index       # where the vector index / metadata will be stored
CHUNK_SIZE=1000         # characters per text chunk
CHUNK_OVERLAP=200       # overlap between chunks
TOP_K=5                 # default number of search results to return

Index your PDFs (one-time or after adding new files):

# Example indexer command; your repo may use a script like index_pdfs.py
python index_pdfs.py --pdf-dir "$PDF_DIR" --index-dir "$INDEX_DIR"

Start the MCP server (example using uvicorn / FastAPI):

uvicorn server:app --host ${MCP_HOST:-127.0.0.1} --port ${MCP_PORT:-3333}

If the project provides a single-run script, you can also run:

python server.py

Adjust the exact command to match the repository’s entrypoint (server.py, main.py, or server:app for ASGI).

Available Tools / Resources

The server typically registers these MCP tools (tool names may vary by implementation). Use the tools endpoint to discover exact names.

  • list_tools

    • Description: Return available tools, their input schemas and metadata.
    • Input: none
    • Output: JSON list of tool descriptors

  • index_pdfs

    • Description: Ingest PDFs from the configured directory and update the vector index.
    • Input: { “pdf_dir”: “/path/to/pdfs” } (optional)
    • Output: { “indexed”: n }

  • search_pdf

    • Description: Run a semantic and keyword search over indexed PDF text.
    • Input: { “query”: “text”, “k”: 5, “filters”: { … } }
    • Output: [ { “doc_id”: “…”, “page”: 12, “snippet”: “…”, “score”: 0.92 } ]

  • get_pdf_page

    • Description: Retrieve raw text (or optionally convert to image) for a specific PDF page.
    • Input: { “doc_id”: “…”, “page”: 3 }
    • Output: { “text”: “…”, “page”: 3, “doc_id”: “…” }

Discover tools and call them via HTTP (examples below).

Example usage

List available tools (replace host/port if configured differently):

curl http://127.0.0.1:3333/tools

Search example (JSON POST to the server’s run endpoint):

curl -X POST http://127.0.0.1:3333/run \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "search_pdf",
    "input": { "query": "contract termination", "k": 5 }
  }'

Python client example using requests:

import requests

url = "http://127.0.0.1:3333/run"
payload = {
    "tool": "search_pdf",
    "input": {"query": "statute of limitations", "k": 3}
}
resp = requests.post(url, json=payload)
print(resp.json())

Returned results typically include a snippet of matching text, the originating document ID or filename, page number, and a relevance score. Use get_pdf_page or open the PDF file directly to present the full context.

Use Cases

  • Personal document search: Quickly find passages across a collection of invoices, contracts, or notes stored locally without uploading sensitive content.
  • Agent augmentation: Wire the MCP server into a local LLM agent so the agent can call search_pdf to retrieve factual context before generating answers.
  • Research and citations: Index academic PDFs and retrieve page-level snippets and references for citation generation or literature reviews.
  • On-prem enterprise workflows: Integrate searchable PDFs into internal automation (ticket triage, knowledge bases) where data must remain on-premises.

Tips and Best Practices

  • Re-index after adding or updating PDFs to keep the search results current.
  • Tune chunk size and overlap to balance search precision vs. context length.
  • Persist the index directory to avoid rebuilding on every restart.
  • If you need higher-quality semantic matches, configure or swap the embedding model used by the indexer (check repository docs for supported models).

If you need further help integrating this MCP server into a specific agent framework or customizing the indexer, consult the repository examples or open an issue on the project’s GitHub page.

Tags:search