lyonzin/knowledge-rag

The MCP-first local RAG server for Claude Code, Cursor, and every AI agent.
**Hybrid search · Cross-encoder reranking · 35 file formats · 100% local · Zero cloud · Enterprise-grade plumbing built-in.**
Quick Start ·
Why knowledge-rag ·
Compare ·
Enterprise Features ·
Docs
---
⭐ Star History
Chart updated daily by GitHub Action
---
🎯 Why knowledge-rag
Most RAG frameworks fall into one of three traps: (1) they require you to ship your data to a cloud API, (2) they hand you 300 building blocks and 0 opinionated defaults, or (3) they bundle RAG as a 5% feature of a much bigger platform you didn't ask for.
**knowledge-rag is an MCP-native local RAG server** for clients such as Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI and Zed. It includes optional bearer authentication, Prometheus metrics, rate limiting, health probes, structured JSON logging and staging-based rebuilds. Configure the transport and access controls for the intended deployment.
🔒 100% local, 0% cloud
Embedding generation, indexing, and retrieval run locally. Model downloads and add_from_url use network access, and configured MCP clients receive retrieved content. Choose the corpus, client permissions, and network exposure to fit your deployment; this project does not certify regulatory compliance.
🚀 Zero-friction setup
pip install knowledge-rag → restart your MCP client → done. **No Docker mandatory. No Ollama required. No separate embedding server.** Everything runs in-process via FastEmbed ONNX. **Works offline** after the first model download.
🛡️ Production-grade OSS
7-pillar quality workflow, a 9-cell OS×Python CI matrix (Linux + Windows + macOS × 3.11/3.12/3.13), and nightly chaos, bounded-memory soak and mutation tests. Inspect the checks on the revision being deployed; CI coverage is not a guarantee of zero defects.
💰 Zero ongoing cost
No token bills. No SaaS tier. No paid features hidden behind a wall. **MIT license, forever.** Runs on the laptop you already have — GPU optional, CPU works fine with FastEmbed ONNX.
---
📊 How knowledge-rag compares to other RAG frameworks
Compare the features needed for your deployment rather than treating framework
checklists as a benchmark. Knowledge-rag combines MCP tools, local embeddings,
ChromaDB persistence, BM25, optional FTS5 and optional reranking in one process.
| Decision | What to verify |
| --- | --- |
| Local or remote processing | Where models run, which client receives content, and which features need network access |
| Retrieval quality | Expected-source queries on your corpus, including its languages and identifiers |
| Performance | Cold initialization, indexing, uncached queries, memory peaks and concurrent use on comparable hardware |
| Operations | Authentication, metrics exposure, backups, recovery and one-writer ownership |
| Extensibility | Supported parsers, model profiles and the public MCP contract |
The audit report records a reproducible local workload
and its limitations. Results against an older implementation of this project are
not speed comparisons against other RAG frameworks.
---
🚀 Quick Start (3 minutes, from zero to your first query)
Pick your integration path — knowledge-rag ships the same server through every channel.
Path 1 — Claude Code, Cursor, Windsurf, Cline, VS Code, Gemini CLI, Zed (MCP)
Drop your PDFs, markdown, code files into documents/. Restart your MCP client. Ask it:
That's it. First query loads the ONNX embedding model (~200MB, one-off download). Subsequent queries are cached and hit sub-second latency.
Path 2 — HTTP / SSE server (multi-user, air-gapped, load-balanced)
- Health probe: curl http://your-host:8179/health → 200 + JSON payload
- Prometheus scrape: http://your-host:9179/metrics
- MCP dispatcher: authenticated via Authorization: Bearer your-secret-token
Multi-client setup (Shared Server via Streamable HTTP)
stdio is ideal when one MCP client owns one knowledge-rag process. If several clients (e.g. Claude, Cursor, LM Studio, or multiple terminal windows) should share one index and one running process, run knowledge-rag once with Streamable HTTP and point each HTTP-capable client at the same endpoint (prompted by #217 and issue #223):
- **Local MCP clients (Cursor, LM Studio, etc.):** Point their remote-server URL directly at http://127.0.0.1:8179/mcp.
- **Claude Custom Connectors (Remote MCP):**
- **Network requirement:** Custom connector requests originate from Anthropic's cloud infrastructure across web, desktop, and mobile, so they cannot reach local 127.0.0.1. You must expose your server via a secure, publicly accessible HTTPS endpoint (e.g. Cloudflare Tunnel, ngrok, or reverse proxy) at https://your-public-domain/mcp. Configure the proxy to send an upstream Host accepted by the HTTP app for server.host (for the default loopback configuration, use 127.0.0.1:8179); forwarding the public hostname unchanged can produce 421 Invalid Host header. Keep bearer authentication and HTTPS enabled. Local claude_desktop_config.json uses command/args for local stdio processes and does not support remote HTTP endpoints.