PDF Knowledgebase

PDF Knowledgebase MCP Server transforms your PDF and Markdown document collections into a semantic, searchable knowledge base that AI assistants can query through the MCP protocol. It supports real-time web access, local-first privacy options, and scalable deployment for personal or team use.

How to use

Connect your MCP client to the server’s HTTP MCP endpoint to perform searches, manage documents, and analyze results. You’ll interact through your MCP client (such as Claude Desktop or VS Code with Continue) by pointing it to the MCP URL and using the provided tools to search across your indexed documents.

Key usage patterns you’ll perform:

• Upload and index new PDFs or Markdown files through the web interface or by placing files in the configured documents directory.
• Run semantic and hybrid searches to quickly locate relevant information across your document collection.
• View generated metadata and summaries to understand document context and structure.
• Use the MCP endpoint from your AI assistant to initiate queries and receive structured results.

How to install

Prerequisites you need before starting:

• A container runtime: Docker or Podman
• An API key for the AI provider you choose to use for embeddings (recommended: DeepInfra API key)
• A folder with your PDF or Markdown documents to index

# Download configuration and create directories
curl -o docker-compose.yml https://raw.githubusercontent.com/juanqui/pdfkb-mcp/main/docker-compose.sample.yml
mkdir -p ./documents ./cache ./logs

# Edit docker-compose.yml and update:
# 1. Volume path: "/path/to/your/documents:/app/documents:rw"
# 2. API key: PDFKB_OPENAI_API_KEY: "your-deepinfra-api-key-here"

Start the server with one of the following options:

• Using Podman (recommended): podman-compose up -d
• Using Docker: docker compose up -d

Access points you’ll use:

• Web Interface: http://localhost:8000
• MCP Endpoint: http://localhost:8000/mcp/
• Health Check: http://localhost:8000/health

Configure your MCP client to point to the server:

• Claude Desktop: use the MCP URL http://localhost:8000/mcp/
• VS Code with Continue: use the MCP URL http://localhost:8000/mcp/

Additional configuration and notes

Environment variables shown for run include the API key used for embeddings. These variables are relevant when you deploy and should be kept secure. The web interface and MCP endpoint run on the same container and expose the MCP transport over HTTP.

For offline privacy, you can run with local embeddings to avoid API costs. The server supports background processing, health checks, and monitoring to ensure reliability as your document collection grows.

Available tools

semanticSearch

Performs semantic similarity searches across document chunks to retrieve contextually relevant results.

hybridSearch

Combines semantic similarity with keyword matching (BM25) for robust results.

reranking

Re-ranks search results using AI models to improve relevance.

localEmbeddings

Supports local embeddings for offline privacy and cost control.

documentSummarization

Auto-generates metadata such as titles, descriptions, and summaries for documents.

webInterface

Web-based UI for document management, processing status, and analytics.

mcpTransport

MCP endpoint to interact with Claude Desktop, VS Code, Continue, and other MCP clients.