Hybrid RAG Project

You run a local MCP Server that exposes a REST API and a Claude integration path to ingest documents, run hybrid retrieval, and answer questions against your own data. It centralizes access to your data, enables fast querying, and lets Claude Desktop or other MCP clients interact with your local RAG stack securely and efficiently.

How to use

You connect to the MCP Server from your client application or Claude Desktop. Start by launching the REST API server so your client can ingest documents and submit queries. You can also enable Claude Desktop integration to run commands directly against your local RAG setup. Use the ingest endpoint to load documents from your data folder, then issue queries to get semantically enriched results combined with keyword search.

How to install

Prerequisites: Python 3.9 or newer, and a local runtime environment to run the MCP server. You will also need to ensure Ollama is installed if you want to leverage embedded LLM capabilities, though the MCP server can operate with local Python-based components.

Step by step, run these commands in order to set up and start the MCP server locally.

# 1. Prepare a Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start the MCP REST API server
python scripts/mcp_server.py

# 4. (Optional) Start Claude Desktop integration by ensuring Claude can reach the MCP server

Configuration and usage notes

The server exposes an HTTP MCP endpoint on your local machine. You can ingest documents from the data directory and then query them using hybrid retrieval. You can also configure Claude Desktop to connect via MCP by setting up a local command that launches the Claude-integrated MCP server component.

Configuration examples

# config/config.yaml
ollama:
  base_url: "http://localhost:11434"
  embedding_model: "nomic-embed-text"
  llm_model: "llama3.1:latest"

data:
  directory: "./data"
  supported_formats:
    - "txt"
    - "pdf"
    - "md"
    - "docx"
    - "csv"

retrieval:
  vector_search_k: 2
  keyword_search_k: 2

mcp_server:
  host: "0.0.0.0"
  port: 8000

vector_store:
  persist_directory: "./chroma_db"

Security and access considerations

Run the MCP server on a trusted host and employ network controls to limit access to authorized clients. When exposing the API, consider using authentication or a private network if your environment requires stricter access controls.

Troubleshooting tips

If you encounter issues starting the server, verify the Python virtual environment is active, ensure all dependencies installed correctly, and confirm the server process is listening on the configured port. Check logs produced by the MCP server for error messages and ensure your data directory contains supported file formats.

Notes on Claude Desktop integration

If you want Claude Desktop to work with your local MCP server, configure the Claude Desktop MCP settings to point to the local HTTP MCP endpoint or use the provided CLI-based workflow to start a Claude-enabled MCP server instance. The integration supports commands to ingest documents, query documents, and check the system status.

Available tools

ingest_documents

Start loading and indexing documents asynchronously from the data/ directory

get_ingestion_status

Monitor the progress of document ingestion, including percentage and current file

query_documents

Query the documents using hybrid search (semantic + keyword)

get_status

Check the RAG system status

list_datasets

List available CSV datasets with columns and row counts

count_by_field

Count rows where a field matches a value for precise numeric results

filter_dataset

Filter dataset rows based on field criteria

get_dataset_stats

Get basic statistics about a dataset