PDF Knowledge Base MCP server

The PDF RAG MCP Server is a powerful document knowledge base system that leverages PDF processing, vector storage, and MCP (Model Context Protocol) to provide semantic search capabilities for PDF documents. You can upload, process, and query PDF documents through a web interface or integrate with AI tools like Cursor via the MCP protocol.

Installation

Prerequisites

• Python 3.8 or later
• uv - Fast Python package installer and resolver
• Git
• Cursor (optional, for MCP integration)

Quick Installation

1. Clone the repository:

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

2. Install uv if you don't have it already:

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

3. Install dependencies using uv:

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

4. Start the application:

   uv run run.py
   

5. Access the web interface at http://localhost:8000

Usage

Web Interface

Once the server is running, you can use the web interface to:

• Upload PDF documents
• Monitor real-time processing status
• Search through your document knowledge base

Uploading Documents

1. Access the web interface at http://localhost:8000
2. Click on "Upload New PDF" and select a PDF file
3. The system will process the file, showing progress in real-time
4. Once processed, the document will be available for searching

Searching Documents

Use the search functionality in the web interface to find relevant information across all your uploaded documents.

MCP Integration with Cursor

To use the PDF RAG server with Cursor:

1. Add the MCP server configuration to your Cursor ~/.cursor/mcp.json file:

   {
     "mcpServers": {
       "pdf-rag": {
         "url": "http://localhost:7800/mcp"
       }
     }
   }
   

2. You can replace localhost with the host IP if you deployed the service elsewhere.

3. After adding this configuration, you will see the MCP server in the Cursor MCP config page. Enable it to use the server.

Production Setup

For a production environment where the static files have already been built:

1. Place your pre-built frontend in the backend/static directory
2. Start the server:

   cd backend
   uv pip install -r requirements.txt
   python -m app.main
   

Troubleshooting

Connection Issues

• Verify that port 8000 is not in use by other applications
• Check that the WebSocket connection is working properly
• Ensure your browser supports WebSockets

Processing Issues

• Check if your PDF contains extractable text (some scanned PDFs may not)
• Ensure the system has sufficient resources (memory and CPU)
• Check the backend logs for detailed error messages

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.