pdf-rag

PDF RAG MCP Server exposes a knowledge base built from uploaded PDF documents. It processes PDFs by extracting text, chunking content, and generating vector embeddings stored in a vector database, enabling semantic search across your documents. The server also communicates via the MCP (Model Context Protocol) so AI tools like Cursor can query your PDF knowledge base directly. You can interact with the system through the provided web interface for uploading and managing PDFs, or connect programmatically via the MCP endpoint to perform queries, chat-style conversations, or context-aware actions with your AI tooling. The MCP integration is designed to be straightforward: configure the Cursor MCP settings to point at the server’s MCP endpoint, and you’ll be able to issue queries that leverage the document corpus rather than just raw PDFs.

Prerequisites:

• Python 3.8 or later
• Git
• Optional: uv (for Python dependency management and fast startup)
• Cursor (optional, for MCP integration)

Step 1: Clone the repository

git clone https://github.com/yourusername/PdfRagMcpServer.git
cd PdfRagMcpServer

Step 2: Install uv (recommended for Python dependency management)

curl -sS https://astral.sh/uv/install.sh | bash

Step 3: Install backend dependencies

uv init .
uv venv
source .venv/bin/activate
uv pip install -r backend/requirements.txt

Step 4: Run the MCP server (example using Python module entrypoint)

python -m app.main

Step 5: Access the web interface and MCP endpoint

• Web UI: http://localhost:8000
• MCP endpoint (for Cursor): http://localhost:8000/mcp

If you prefer to run the backend and frontend separately, follow the Development Setup in the README to run the backend with uvicorn and the frontend with npm. You can also run the server via the traditional Python approach shown above.

Tips and common issues:

• Ensure port 8000 is available for the FastAPI backend and that the WebSocket path is accessible for real-time processing updates.
• If you see PDF parsing failures, verify that the PDFs contain extractable text and that the server has sufficient memory for embedding generation.
• For Cursor integration, ensure the MCP endpoint URL matches your deployment (localhost vs. a deployed host) and that the server is reachable from the Cursor environment.
• If using uv to manage dependencies, remember to activate the virtual environment before running the server.
• When deploying in production, pre-build the frontend (static assets) and point the backend to serve those assets from backend/static.