knowledge-rag MCP server
Commit Nov 15, 2026Indexes local documents and code so an AI client can search them with hybrid BM25 and vector retrieval plus cross-encoder reranking.
Also known as lyonzin/knowledge-rag
- Stars
- 306
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is knowledge-rag MCP?
knowledge-rag indexes local documents and code so an AI client can search them with hybrid BM25 and vector retrieval plus cross-encoder reranking. It exposes 13 tools, such as search_knowledge, get_document, search_similar.
Summary generated from the project's README
About knowledge-rag MCP server
Indexing local documents and code for intelligent retrieval is what knowledge-rag enables for developers using Claude Code, Cursor, or VS Code. This local RAG server provides 13 specialized tools that allow an AI client to search through your machine's files using a combination of BM25 keyword matching and vector similarity. It operates entirely within a single Python process using embedded ChromaDB and FastEmbed ONNX models, meaning you do not need Docker, a separate database server, or any external API keys to function.
Once you place files in the designated documents folder, the server automatically parses, chunks, and embeds them. It uses a hybrid search approach with weighted reciprocal rank fusion and a cross-encoder reranker to ensure high precision. The system supports various formats including Markdown, PDF, and code files, while maintaining an offline workflow once the initial models are cached. Because it runs locally, your data remains on your machine while providing the context necessary for an LLM to answer complex questions about your specific codebase or documentation.
What you can do with it
- 1Search local codebasesAsk your AI agent to find specific functions or classes within your local project files.
- 2Query technical documentationRetrieve precise information from PDF or Markdown documentation using hybrid keyword and semantic search.
- 3Automate knowledge updatesKeep your AI's context up to date by automatically indexing new or modified files in a watched directory.
Written from the project's README. Every use case is checked against a quote from it.
knowledge-rag MCP tools 13
Detected from the READMEsearch_knowledgeget_documentsearch_similarevaluate_retrievallist_documentslist_categoriesget_index_statsadd_documentupdate_documentremove_documentadd_from_urlreindex_documents
| search_knowledge | — | |
| get_document | — | |
| search_similar | — | |
| evaluate_retrieval | — | |
| list_documents | — | |
| list_categories | — | |
| get_index_stats | — | |
| add_document | — | |
| update_document | — | |
| remove_document | — | |
| add_from_url | — | |
| reindex_documents | — |
Show all 13 toolsShow fewer tools
get_reindex_status
| get_reindex_status | — |
Configuration
KNOWLEDGE_RAG_DIRKNOWLEDGE_RAG_SINGLE_INSTANCE
| Name | Description | |
|---|---|---|
| KNOWLEDGE_RAG_DIR | — | |
| KNOWLEDGE_RAG_SINGLE_INSTANCE | — |
Automated checks
Ran Nov 12, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubknowledge-rag: local RAG server for Claude Code, Cursor and other MCP clients
knowledge-rag is a local retrieval-augmented generation (RAG) server for the Model Context Protocol (MCP). It indexes the documents and code on your machine and gives Claude Code, Cursor, VS Code and other MCP clients 13 tools to search them, using hybrid search (BM25 keywords plus vector similarity) with cross-encoder reranking on by default. Everything runs in one Python process with embedded ChromaDB and FastEmbed ONNX models: no Docker, no database server, no API key. Indexing and search work offline once the models are cached.
- 11.1 ms median uncached hybrid query on CPU, 6.1 ms on CUDA: 36 queries over 149 chunks on one Windows host, reranker off (audit)
- 0.03 ms median for a repeated query served from the cache, same workload (audit)
- 75,016 chunks from 5,889 documents: full rebuild completed in a production reproduction (v4.8.3)
- 1,500+ tests collected on each of 9 OS × Python CI cells (platform-specific ones skip), 84% line coverage against an 80% floor (CI run, 2026-11-06)
Install and register with Claude Code (needs Python 3.11+ and Node.js 16+):
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-rag
Put files in ~/knowledge-rag/documents/ and ask your agent to search them. The folder is created on first start, new and changed files are indexed automatically, and the models (about 150 MB) download the first time they are needed.
Install · Results · How it works · Tools · Skills · Comparison · FAQ · Docs
Star history
Measured results
Measurements from the project's own audits. They come from one host and small corpora, so treat them as orders of magnitude for your planning, not as guarantees.
| Measurement | CPU | NVIDIA CUDA |
|---|---|---|
| Hybrid query, uncached, median | 11.13 ms | 6.10 ms |
| Hybrid query, uncached, p95 | 13.91 ms | 7.44 ms |
| Repeated query (cache hit), median | 0.033 ms | 0.028 ms |
| Initial indexing, including first model load | 13.655 s | 0.832 s |
| Sampled peak process memory (RSS) | 1,416 MB | 990 MB |
Workload: scripts/audit_retrieval.py indexing 7 public repository documents (149 chunks) into a temporary ChromaDB and FTS5 index; 36 uncached queries; cross-encoder disabled to isolate retrieval; Windows 11, RTX 3080 Ti, Python 3.12.7, FastEmbed 0.8.1, ChromaDB 1.5.9, model BAAI/bge-small-en-v1.5, Hugging Face offline mode. Source: audit 2026-10-03.
| Retrieval check | Result | Workload and source |
|---|---|---|
| Expected source in the top 5 | 12 of 12 questions; MRR@5 0.875 (English), 0.792 (Portuguese) | 6 English and 6 Portuguese questions over the same 149 chunks, default English model; a small smoke test, not a general quality claim (audit) |
| Cross-encoder rerank of 8 candidates | 141.9 ms first call including model load, 19.7 ms next call (CPU) | One English and one Portuguese query, network blocked (audit) |
| Large corpus | Full rebuild completed and filled 75,016 FTS5 rows on the first attempt | 5,889 documents / 75,016 chunks, v4.8.3 reproduction (CHANGELOG) |
- BM25 memory: retained Python memory fell from 120.7 MB to 26.9 MB (−77.75%) for 10,000 documents / 1.99 million tokens after the token pool was added in v4.10.0 (audit).
- Metrics memory: 100,001 metric observations retained 328 bytes instead of 3,201,024 (audit).
- Multilingual model: on a 60-question diagnostic set over a private ~70,000-chunk corpus,
intfloat/multilingual-e5-largefound the expected source for 36 questions against 37 for the defaultBAAI/bge-small-en-v1.5; re-embedding 70,083 chunks on CUDA took 1,186.58 s (audit 2026-10-04). - Historical baseline: v4.7.1 microbenchmarks and a 100-document rebuild on CPU (perf-baseline-v4.7.1). The ratios apply to those workloads only.
- Live dashboard: the benchmark dashboard tracks CI microbenchmarks. They use mocked storage and models, so they answer a different question than the real-model numbers above.
How it works
- Ingest. Files under
documents/are parsed by format: code files get their function, class and import names as metadata, notebooks keep only Markdown and code cells, PDFs contribute their text. Markdown is split at##/###sections; every other format is cut into 1,000-character chunks with 200 characters of overlap. Chunks are de-duplicated by SHA-256, embedded with FastEmbed (defaultBAAI/bge-small-en-v1.5, 384 dimensions) and stored in an embedded ChromaDB. - Watch. While the server runs, a watcher re-indexes changed files after 10 seconds without new changes. Full rebuilds fill a staging collection and swap it in after validation, so searches keep using the current index.
- Search.
search_knowledgechecks a query cache (100 entries, 5-minute TTL), runs BM25 over an inverted index and vector search, fuses both rankings with weighted reciprocal rank fusion (hybrid_alpha, default 0.3, leaning towards keywords) and reranks the top candidates with theXenova/ms-marco-MiniLM-L-6-v2cross-encoder. With the opt-in FTS5 fast path, identifier-like queries such as CVE IDs, ticket keys and hashes go to SQLite FTS5 first. - Answer. Results go back to the MCP client with the file path, chunk index, snippet and scores. The client's model writes the answer; knowledge-rag never calls an LLM.
- Serve. Over stdio for one client, or as one Streamable HTTP or SSE server for many. HTTP mode answers health probes first, then checks the bearer token. Every tool call passes through the optional rate limiter and metrics.
config.yamland five presets configure all of it.
flowchart TB
subgraph CLIENTS["MCP clients"]
direction LR
C1[Claude Code]
C2[Claude Desktop]
C3[Cursor]
C4[Windsurf]
C5[VS Code · other stdio or HTTP clients]
end
subgraph TRANSPORT["Transport"]
T1[stdio<br/>1 process per client]
T2[Streamable HTTP / SSE<br/>1 server for N clients]
end
subgraph MIDDLEWARE["ASGI middleware (HTTP transports)"]
M1[HealthMiddleware<br/>/health · /healthz]
M2[BearerAuthMiddleware<br/>constant-time compare]
end
subgraph MCP["13 MCP tools (contract checked in CI)"]
W[Tool wrappers<br/>optional rate limit · metrics]
MT1[search_knowledge]
MT2[get_document · search_similar]
MT3[add_document · add_from_url · update · remove]
MT4[reindex_documents · get_reindex_status]
MT5[list_documents · list_categories · get_index_stats · evaluate_retrieval]
end
subgraph SEARCH["Retrieval pipeline"]
QC[Query cache<br/>LRU 100 · 5-min TTL]
R[Query router<br/>regex, FTS5 fast path only]
F[FTS5 fast path<br/>opt-in lexical retrieval]
H[Hybrid search]
BM[BM25<br/>inverted index]
SE[Vector search<br/>FastEmbed ONNX, lazy-loaded]
RRF[Weighted reciprocal rank fusion]
CE[Cross-encoder rerank<br/>MiniLM-L-6-v2]
end
subgraph STORAGE["Local storage (data_dir)"]
CH[ChromaDB<br/>vectors + metadata<br/>WAL with HTTP transports]
FT[SQLite FTS5<br/>lexical index<br/>WAL + busy timeout]
MD[index_metadata.json<br/>durable state]
end
subgraph INGEST["Document ingestion"]
FS[documents/ folder]
WD[Watcher<br/>10 s debounce]
PA[Format parsers<br/>MD · PDF · DOCX · code · IaC · IPYNB]
CK[Chunker<br/>Markdown sections · 1,000-char windows]
EM[FastEmbed ONNX<br/>default bge-small-en-v1.5, 384-d]
DD[SHA-256 dedup]
SW[Staging rebuild<br/>rollback on handled publication failure]
end
subgraph OBS["Observability (opt-in)"]
PM[Prometheus /metrics<br/>separate port, HTTP transports]
LG[Structured JSON logs]
HC[Health payload<br/>version · uptime · cache stats]
end
subgraph CFG["Configuration"]
YM[config.yaml<br/>+ 5 presets]
end
CLIENTS -->|MCP over stdio| T1
CLIENTS -.->|MCP over HTTP| T2
T1 --> W
T2 --> M1 --> M2 --> W
W --> MT1 & MT2 & MT3 & MT4 & MT5
MT1 --> QC
QC -->|cache miss| R
R -->|identifier-like| F
R -->|everything else| H
H --> BM
H --> SE
F --> FT
BM --> CH
SE --> CH
BM --> RRF
SE --> RRF
RRF --> CE
CE --> QC
MT2 --> CH
MT3 --> INGEST
MT4 --> SW
MT5 --> CH
FS --> WD --> PA
PA --> CK --> DD --> EM --> CH
SW -.->|validated swap| CH
SW -.-> FT
CH -.-> MD
W -.->|instrumented| PM
W -.->|logs| LG
M1 --> HC
YM -.-> SEARCH
YM -.-> STORAGE
YM -.-> OBS
YM -.-> MIDDLEWARE
classDef client fill:#3776AB,stroke:#1e5a8a,color:#fff
classDef transport fill:#00A67E,stroke:#006e54,color:#fff
classDef middleware fill:#6b46c1,stroke:#4c1d95,color:#fff
classDef storage fill:#4b5563,stroke:#1f2937,color:#fff
classDef obs fill:#dc2626,stroke:#7f1d1d,color:#fff
classDef ingest fill:#b45309,stroke:#78350f,color:#fff
class C1,C2,C3,C4,C5 client
class T1,T2 transport
class M1,M2 middleware
class CH,FT,MD storage
class PM,LG,HC obs
class FS,WD,PA,CK,EM,DD,SW ingest
Component ownership, memory and concurrency boundaries and the hybrid_alpha weights: docs/ARCHITECTURE.md.
Install
Every path below runs the same server. Each claude mcp add sets KNOWLEDGE_RAG_DIR, the folder that holds config.yaml, documents/, data/ and models_cache/. Without it, the server picks a folder from its install location and the working directory the client starts it in, which can be a project you did not intend (config.py).
Claude Code with the npx launcher
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-rag
The npm package is a launcher. It finds Python 3.11+ (python3/python, or python/py -3 on Windows), creates a virtual environment in ~/.knowledge-rag/venv, installs the matching knowledge-rag version from PyPI and starts the server over stdio. --install-only does the installation once ahead of time, so the client's first start does not wait for pip. A new npm version reinstalls the package on the next start. If a client on native Windows fails to start npx, register cmd /c npx -y knowledge-rag instead.
pip in a virtual environment
python3 -m venv ~/knowledge-rag/venv
~/knowledge-rag/venv/bin/python -m pip install knowledge-rag
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag \
-- ~/knowledge-rag/venv/bin/python -m mcp_server.server
On Windows (PowerShell), use python and $HOME\knowledge-rag\venv\Scripts\python.exe in place of python3 and ~/knowledge-rag/venv/bin/python.
Optional: knowledge-rag init, run inside ~/knowledge-rag with the virtual environment active, copies config.example.yaml and the five presets and creates documents/. It does not create config.yaml or register the server: copy the template or a preset to config.yaml yourself. Without a config.yaml, the defaults apply, including all 33 default file types.
Docker
The image is published for linux/amd64 and linux/arm64. For stdio, the client starts one container per session:
claude mcp add knowledge-rag -s user -- docker run -i --rm \
-v ~/knowledge-rag/documents:/app/documents \
-v ~/knowledge-rag/data:/app/data \
-v knowledge-rag-models:/app/models_cache \
ghcr.io/lyonzin/knowledge-rag:latest
The image runs python -m mcp_server.server, which reads /app/config.yaml and defaults to stdio on 127.0.0.1. To serve HTTP from a container, mount a config that listens on all container interfaces and pass --transport:
mkdir -p ~/knowledge-rag
cat > ~/knowledge-rag/config.yaml <<'EOF'
server:
host: "0.0.0.0"
auth:
bearer_token: "replace-with-a-long-random-token"
EOF
docker run -d --name knowledge-rag -p 127.0.0.1:8179:8179 \
-v ~/knowledge-rag/config.yaml:/app/config.yaml:ro \
-v ~/knowledge-rag/documents:/app/documents \
-v ~/knowledge-rag/data:/app/data \
-v knowledge-rag-models:/app/models_cache \
ghcr.io/lyonzin/knowledge-rag:latest --transport streamable-http
curl http://127.0.0.1:8179/health
claude mcp add --transport http knowledge-rag http://127.0.0.1:8179/mcp \
# if server.auth.bearer_token is set, add the token as a Bearer auth header
The image builds its model copies into FastEmbed's default cache, but the server reads /app/models_cache, so the models download again the first time they are needed. The knowledge-rag-models volume keeps them across containers.
Shared HTTP server for several clients
stdio fits one client that owns one process. For several clients on one index (Claude Code, Cursor, LM Studio, more terminals), run one Streamable HTTP server and point every client at it (#217, #223):
# ~/knowledge-rag/config.yaml
server:
transport: "streamable-http" # "sse" for clients that only speak SSE
host: "127.0.0.1"
port: 8179
auth:
bearer_token: "replace-with-a-long-random-token"
rate_limit:
enabled: true
requests_per_minute: 60
burst: 10
metrics:
enabled: true
port: 9179 # binds 0.0.0.0 with no auth: firewall it
logging:
format: "json"
KNOWLEDGE_RAG_DIR=~/knowledge-rag knowledge-rag # run from the venv where you installed it
curl http://127.0.0.1:8179/health # {"status":"ok","version":"5.0.0",...}
claude mcp add --transport http knowledge-rag http://127.0.0.1:8179/mcp \
# if server.auth.bearer_token is set, add the token as a Bearer auth header
| Transport | Clients per server process | Who runs the process | Use it for |
|---|---|---|---|
stdio (default) |
1 | The MCP client, per session | One client; models load in each process on first use |
streamable-http |
Many | You, one background server | Several clients sharing one index and one model load (preferred) |
sse |
Many | You, one background server | HTTP clients that only support SSE |
HTTP transports switch on the single-instance lock (KNOWLEDGE_RAG_SINGLE_INSTANCE=1), so a second server cannot open the same data directory. The default host is 127.0.0.1. If you bind to 0.0.0.0 or serve a network, set server.auth.bearer_token and put TLS in front with a reverse proxy such as Caddy or Nginx; without a token, the server prints a warning that the endpoint is unauthenticated.
- Network requirement: custom connector requests come from Anthropic's cloud on web, desktop and mobile, so they cannot reach
127.0.0.1. Expose the server through a secure public HTTPS endpoint (for example Cloudflare Tunnel, ngrok or a reverse proxy) athttps://your-public-domain/mcp. Configure the proxy to send an upstreamHostthat the HTTP app accepts forserver.host(with the default loopback configuration,127.0.0.1:8179); forwarding the public hostname unchanged can produce421 Invalid Host header. Keep bearer authentication and HTTPS on. A localclaude_desktop_config.jsonusescommand/argsfor local stdio processes and does not support remote HTTP endpoints. - Setup and auth: in Claude (Pro/Max: Customize > Connectors > + Add > Add custom connector; Team/Enterprise owners: Organization settings > Connectors), enter the public endpoint. Under Request headers, set
AuthorizationtoBearer <your-token>, matchingserver.auth.bearer_tokeninconfig.yaml. See Anthropic's custom connectors guide.
Other MCP clients
Any client that starts a stdio MCP server from a command, or connects to a Streamable HTTP endpoint, can use knowledge-rag. The installation guide has the exact JSON for each of these:
| Client | Where the server entry goes |
|---|---|
| Claude Desktop | claude_desktop_config.json, under mcpServers (Settings → Developer → Edit Config) |
| Cursor | ~/.cursor/mcp.json or .cursor/mcp.json, under mcpServers |
| Windsurf | ~/.codeium/windsurf/mcp_config.json, under mcpServers |
| Antigravity | ~/.gemini/antigravity/mcp_config.json, under mcpServers |
| VS Code (Copilot) | .vscode/mcp.json, under servers, with "type": "stdio" |
| opencode | opencode.json, under mcp, with command as an array |
{
"mcpServers": {
"knowledge-rag": {
"command": "npx",
"args": ["-y", "knowledge-rag"],
"env": { "KNOWLEDGE_RAG_DIR": "~/knowledge-rag" }
}
}
}
[!WARNING] One writer per data directory. Over stdio, each MCP client starts and owns its own knowledge-rag process. Do not run a second writer against the same
data_dirwhile that client is open: on Windows, two writers corrupted the ChromaDB HNSW segment (#216). Add"KNOWLEDGE_RAG_SINGLE_INSTANCE": "1"to the client'senvblock as a safety net, or share one HTTP server. Running CLI commands safely: docs/single-instance.md.
[!WARNING] Keep
data_dirout of cloud-sync folders. OneDrive (includingOneDrive - <tenant>), iCloud Drive, Dropbox, Google Drive, Box, pCloud, MEGAsync, Nextcloud/ownCloud and Sync hold handles on the live index while they upload it. That races with ChromaDB's HNSW memory maps and SQLite WAL writes and can crash the process (0xC0000005on Windows,SIGBUSelsewhere); startup auto-repair then moves the index todata/backups/auto-repair-*and you reindex from scratch. Since v4.11.0, startup stops with exit code 78 (EX_CONFIG) whendata_dirresolves under one of these providers. Use a local path such as%LOCALAPPDATA%\knowledge-rag\dataon Windows or~/.local/share/knowledge-rag/dataon Linux and macOS, or setpaths.allow_cloud_sync: trueto accept the risk.
All install methods, GPU setup and troubleshooting for each client: docs/INSTALLATION.md.
The 13 MCP tools
| Tool | What it does |
|---|---|
search_knowledge |
Hybrid BM25 + vector search with cross-encoder reranking; filters by category, folders (include_folders, exclude_folders) and min_score |
get_document |
Returns the full content of one indexed file |
search_similar |
Finds documents similar to an indexed file |
evaluate_retrieval |
Reports MRR@5 and Recall@5 for your own query → expected file pairs |
list_documents |
Lists indexed documents, 100 per page by default (up to 200 with limit), paged with offset |
list_categories |
Lists categories, derived from folder paths, with document counts |
get_index_stats |
Document and chunk counts, embedding model, BM25 status, cache hit rate, watcher status, HNSW self-recall probe |
add_document |
Saves text as a file under documents/ and indexes it |
update_document |
Replaces a document's content and re-indexes it |
remove_document |
Removes a document's chunks from the index, and optionally the file |
add_from_url |
Fetches an http(s) page, strips the HTML, saves it as Markdown with a provenance marker and indexes it |
reindex_documents |
Incremental by default; force re-embeds every file, full_rebuild builds and swaps a staging collection; runs in the background |
get_reindex_status |
Reports the progress of a background reindex |
Each result carries source (the file path), chunk_index and, in snippet mode, match_offset (a character offset into the content), so citations point to a file and chunk, not a line number. score is normalized per query, so the top result is always 1.0 and min_score filters relative to the other results; compare reranker_score, the raw cross-encoder score, across queries. Parameters, return shapes and examples: docs/API.md.
knowledge-rag MCP questions
What tools does knowledge-rag MCP provide?
It exposes 13 tools, including search_knowledge, get_document, search_similar, evaluate_retrieval, list_documents.
Does knowledge-rag need Docker, a database server or an API key?
No. It runs as one Python process with embedded ChromaDB and FastEmbed ONNX models, so no Docker, database server or API key is required.
How does knowledge-rag search work?
It runs BM25 keyword search and vector search, fuses the rankings with weighted reciprocal rank fusion, then reranks the top candidates with a cross-encoder.
Does knowledge-rag work offline?
Yes, once the roughly 150 MB of models are cached, indexing and search work offline.
Does knowledge-rag re-index files when they change?
Yes. A watcher re-indexes changed files in the documents folder after 10 seconds without new changes.
How many tools and file types does knowledge-rag support?
It exposes 13 MCP tools and handles 33 file types, including code files and notebooks.