claude-rag — MCP RAG Server for Markdown Knowledge Bases

MCP server that indexes a folder of .md files into a local SQLite vector store and exposes semantic search as Claude Code tools.

Stack: Python · sentence-transformers (all-MiniLM-L6-v2, ~90MB, CPU-only) · SQLite · MCP stdio

Tools exposed

Related MCP server: flightlog

Setup

1. Clone

# Default layout: repo sits inside the KB folder
# KB files (.md) go in the parent directory
git clone https://github.com/sangelastro/claude-rag ~/.claude/my-kb/rag

Or clone anywhere and point to your KB folder via env var (see step 3).

2. Install dependencies

cd ~/.claude/my-kb/rag
pip install -r requirements.txt

On first run the model (all-MiniLM-L6-v2, ~90MB) is downloaded automatically from HuggingFace.

3. Register in Claude Code

Add to ~/.claude.json under mcpServers:

"my-kb": {
  "command": "python",
  "args": ["/absolute/path/to/rag/server.py"],
  "env": {
    "KB_RAG_DIR": "/absolute/path/to/your/kb/folder"
  }
}

• KB_RAG_DIR — folder containing your .md files (default: ../ relative to server.py)

• KB_RAG_DB — SQLite database path (default: kb.db next to server.py)

If the repo is cloned inside the KB folder (as in the example above), both env vars can be omitted.

4. Restart Claude Code

The server starts automatically. On first launch it indexes all .md files in KB_RAG_DIR.

File structure

rag/
├── server.py          # MCP server
├── requirements.txt
├── .gitignore
├── README.md
├── architecture.html  # Technical documentation
└── kb_rag_slides.html # Architecture slide deck

kb.db is generated locally and excluded from git.

How it works

1. Chunking — each .md file is split on ## headers; frontmatter is stripped

2. Embedding — chunks are encoded with all-MiniLM-L6-v2 (384 dimensions)

3. Storage — vectors stored as float32 BLOBs in SQLite (no external vector DB)

4. Search — cosine similarity computed in numpy over all chunks; top-K returned

5. Invalidation — mtime-based: only modified files are re-indexed on startup

Environment variables