OpenRAG Server

Python 3.12 License: MIT Code style: ruff

An open-source MCP server for RAG over personal documents. Supports three parallel strategies — Traditional, Contextual, and Graph RAG — with all data stored locally for privacy.

---

Quick Start (Docker)

No Python or conda required.

# 1. Clone the repository
git clone https://github.com/janik96v/OpenRAG.git
cd OpenRAG

# 2. Copy and adjust the config (change NEO4J_PASSWORD etc.)
cp .env.docker.example .env

# 3. Start everything
docker compose up -d

Neo4j and the MCP server start automatically. ChromaDB data is persisted in ./chroma_db, Neo4j data in a Docker volume.

For Contextual and Graph RAG, Ollama must run on your host:

brew install ollama        # macOS — Linux/Windows: https://ollama.ai/download
ollama serve
ollama pull llama3.2:3b

Traditional RAG only? Set CONTEXTUAL_ENABLED=false and GRAPH_ENABLED=false in .env — no Ollama needed.

See docs/installation.md for the full setup guide including configuration options and troubleshooting.

---

Configure Claude Code / Claude Desktop

Claude Code (CLI)

claude mcp add openrag -- docker compose \
  -f /absolute/path/to/OpenRAG/docker-compose.yml \
  run --rm -i openrag

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent config file on your OS:

{
  "mcpServers": {
    "openrag": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/OpenRAG/docker-compose.yml",
        "run", "--rm", "-i", "openrag"
      ]
    }
  }
}

Replace /absolute/path/to/OpenRAG/docker-compose.yml with your actual path. Restart Claude Desktop after saving.

---

MCP Tools

Tool	Description
ingest_text	Ingest raw text content. Traditional RAG is immediate; Contextual and Graph RAG run in the background.
query_documents	Semantic search. Choose rag_type ("traditional", "contextual", "graph") and optionally max_hops (1–5) for Graph RAG.
list_documents	List all ingested documents with metadata.
delete_document	Remove a document from all RAG collections.
get_stats	System statistics: collection sizes, configuration, background task status.

---

RAG Strategy Comparison

	Traditional	Contextual	Graph
Speed	Fastest	Background	Background
Accuracy	Good	Better	Best for relationships
Use Case	Direct facts	Complex queries	Multi-hop reasoning
Dependencies	ChromaDB	+ Ollama	+ Ollama + Neo4j
Collections	1	2	3

---

Architecture

src/openrag/
├── server.py                      # MCP server entry point
├── config.py                      # Centralized configuration (pydantic-settings)
├── core/
│   ├── chunker.py                 # Token-aware text chunking (tiktoken)
│   ├── embedder.py                # Sentence-transformers embeddings
│   ├── vector_store.py            # Traditional RAG (ChromaDB)
│   ├── contextual_processor.py    # Context generation (Ollama)
│   ├── contextual_vector_store.py # Dual-collection management
│   ├── graph_processor.py         # Entity extraction (Ollama + Neo4j)
│   ├── graph_vector_store.py      # Triple-collection + graph traversal
│   └── ollama_client.py           # Ollama API client
├── tools/                         # MCP tool implementations
├── models/                        # Pydantic data models
└── utils/                         # Logging, validation, background tasks

All three RAG types share the same ChromaDB instance via separate collections:

• Traditional → documents
• Contextual → documents + documents_contextual
• Graph → documents + documents_contextual + documents_graph + Neo4j

---

Smoke Tests

Manual end-to-end scripts for verifying each RAG strategy are in tests/quick/:

# Traditional RAG (no external dependencies)
python tests/quick/test_normalRAG.py

# Contextual RAG (requires Ollama)
python tests/quick/test_contextualRAG.py

# Graph RAG (requires Ollama + Neo4j, takes 3–5 min)
python tests/quick/test_graphRAG.py

For automated unit/integration tests, run pytest tests/.

---

Documentation

Guide	Description
docs/installation.md	Docker setup, configuration, MCP wiring, troubleshooting
docs/quick-start.md	Step-by-step usage guide
docs/architecture.md	System design deep-dive

---

License

MIT License — see LICENSE