What are the requirements for Hybrid RAG Project?

Hybrid RAG Project requires a compatible MCP client such as Claude Desktop, Claude Code, or Cursor. No additional environment variables are needed for basic setup.

Is Hybrid RAG Project free to use?

Yes, Hybrid RAG Project is open source and free to use. You can find the source code on GitHub.

What MCP clients support Hybrid RAG Project?

Hybrid RAG Project works with any MCP-compatible client including Claude Desktop (Anthropic's official desktop app), Claude Code (CLI tool), Cursor, and other editors with MCP support.

How do I configure Hybrid RAG Project?

Configure Hybrid RAG Project by adding it to your MCP client's config file. For Claude Desktop, edit claude_desktop_config.json and add the server configuration. See the Configuration section above for a ready-to-use example.

Hybrid RAG Project MCP Server

Q: What tools does Hybrid RAG Project provide?

query: Performs a hybrid search across the document store using both semantic and keyword matching.. ingest: Ingests new documents from the data directory into the vector store..

Q: How do I install Hybrid RAG Project?

Install Hybrid RAG Project by running: git clone && cd hybrid-rag-project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal

git clone <your-repo-url>
cd hybrid-rag-project
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal

claude mcp add hybrid-rag-project -- python "<FULL_PATH_TO_HYBRID_RAG_PROJECT>/dist/index.js"

Replace <FULL_PATH_TO_HYBRID_RAG_PROJECT>/dist/index.js with the actual folder you prepared in step 1.

README.md

A generalized RAG system with hybrid search capabilities for any documents.

Hybrid RAG Project

A generalized Retrieval-Augmented Generation (RAG) system with hybrid search capabilities that works with any documents you provide. Combines semantic (dense vector) search and keyword (sparse BM25) search for optimal document retrieval, with an MCP server API for easy integration.

🎯 Key Features: Multi-format support • Local LLM • Claude Desktop integration • Structured data queries • Document-type-aware retrieval

🚀 Quick Start (No MCP Required!)

You don't need Claude Desktop or MCP to use this project! Just run:

# 1. Make sure Ollama is running
ollama serve

# 2. Activate virtual environment
source .venv/bin/activate

# 3. Start conversational demo (recommended)
python scripts/demos/conversational.py

# Or use the shortcut
./scripts/bin/ask.sh

That's it! Ask questions about the 43,835 document chunks in the sample dataset.

📖 See Quick Start Guide for complete usage instructions. 📚 Browse all documentation in the docs/ folder or start with docs/README.md.

Overview

This project implements a hybrid RAG system that combines:

Semantic Search: Dense vector embeddings for understanding meaning and context
Keyword Search: BM25 sparse retrieval for exact keyword matching
Hybrid Fusion: Reciprocal Rank Fusion (RRF) to combine results from both methods
MCP Server: Both REST API and Model Context Protocol server for Claude integration
Multi-format Support: Automatically loads documents from various file formats

The hybrid approach ensures better retrieval accuracy by leveraging the strengths of both search methods.

Features

Vector-based semantic search using Chroma and Ollama embeddings
BM25 keyword search for exact term matching
Ensemble retriever with Reciprocal Rank Fusion (RRF)
Integration with local Ollama LLM for answer generation
Support for multiple document formats (TXT, PDF, MD, DOCX, CSV)
Automated document loading from data directory
RESTful API server with /ingest and /query endpoints
Model Context Protocol (MCP) server for Claude Desktop/API integration
Configuration-driven architecture (no hardcoded values)
Persistent vector store for faster subsequent queries

Architecture

User Documents → data/ directory
                      ↓
            Document Loader
                      ↓
Query → Hybrid Retriever → [Vector Retriever + BM25 Retriever]
                         → RRF Fusion
                         → Retrieved Context
                         → LLM (Ollama)
                         → Final Answer

Prerequisites

Python 3.9+
Ollama installed and running locally
Required Ollama models:
- llama3.1:latest (or another LLM model)
- nomic-embed-text (or another embedding model)

Installing Ollama

Visit ollama.ai to download and install Ollama for your platform.

After installation, pull the required models:

ollama pull llama3.1:latest
ollama pull nomic-embed-text

Verify Ollama is running:

curl http://localhost:11434/api/tags

Installation

Clone the repository:

git clone <your-repo-url>
cd hybrid-rag-project

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Project Structure

hybrid-rag-project/
├── src/
│   └── hybrid_rag/            # Core application package
│       ├── __init__.py        # Package initialization
│       ├── document_loader.py # Document loading utility
│       ├── structured_query.py# CSV query engine
│       └── utils.py           # Logging and utility functions
├── scripts/
│   ├── run_demo.py            # Main demonstration script
│   ├── mcp_server.py          # REST API server
│   └── mcp_server_claude.py   # MCP server for Claude integration
├── config/
│   ├── config.yaml            # Configuration file
│   └── claude_desktop_config.json # Sample Claude Desktop MCP config
├── docs/
│   ├── INSTALLATION.md        # Detailed installation guide
│   ├── STRUCTURED_QUERIES.md  # CSV query documentation
│   ├── ASYNC_INGESTION.md     # Async ingestion guide
│   └── SHUTDOWN.md            # Shutdown handling guide
├── data/                      # Sample data files (13 files included)
│   ├── *.csv                  # 7 CSV files (structured data)
│   ├── *.md                   # 5 Markdown files (unstructured)
│   └── *.txt                  # 1 Text file (technical specs)
├── chroma_db/

Tools (2)

queryPerforms a hybrid search across the document store using both semantic and keyword matching.

ingestIngests new documents from the data directory into the vector store.

Configuration

claude_desktop_config.json

{ "mcpServers": { "hybrid-rag": { "command": "python", "args": ["/path/to/hybrid-rag-project/scripts/mcp_server_claude.py"] } } }

Try it

→Search the local documents for information regarding the project's architecture.

→Find relevant documents about the installation process using keyword matching.

→Query the document store for details on how the hybrid fusion method works.

Frequently Asked Questions

What are the key features of Hybrid RAG Project?

Combines semantic vector search with BM25 keyword matching. Uses Reciprocal Rank Fusion (RRF) for optimal retrieval accuracy. Supports multiple file formats including TXT, PDF, MD, DOCX, and CSV. Integrates with local Ollama LLM for private document querying. Persistent vector store using Chroma for faster subsequent queries.

What can I use Hybrid RAG Project for?

Querying large collections of technical documentation for specific implementation details. Performing hybrid searches across mixed structured CSV data and unstructured markdown files. Building a private, local-only RAG pipeline for sensitive document analysis. Enhancing Claude's context with domain-specific knowledge from local files.

How do I install Hybrid RAG Project?

Install Hybrid RAG Project by running: git clone <your-repo-url> && cd hybrid-rag-project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

What MCP clients work with Hybrid RAG Project?

Hybrid RAG Project works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Hybrid RAG Project docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.

Open Conare

View all search servers →