Log inSubmit server
Knowledge Rag logo

Knowledge Rag

by lyonzin

Local MCP RAG for indexed files, combining semantic search, BM25, reranking, document management, and retrieval evaluation.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Knowledge Rag

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "lyonzin-knowledge-rag": {
      "command": "uvx",
      "args": [
        "knowledge-rag"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

lyonzin/knowledge-rag is a local-first MCP knowledge base for Claude Code and other MCP clients, indexing documents for semantic, BM25, and cross-encoder-reranked retrieval. It supports markdown-aware ingestion, category filters, similar-document discovery, full-document retrieval, and tools for adding, updating, removing, and evaluating indexed content. Reach for it when an agent needs searchable local documentation or a self-hosted corpus; local indexing and retrieval work offline after model download, while URL ingestion requires network access.

Use cases

  • Search local security notes by concept or exact technical term
  • Browse and retrieve full Markdown documents from an indexed corpus
  • Ingest public documentation or writeups directly from URLs
  • Evaluate retrieval quality after changing or expanding a knowledge base

Key features

  • Hybrid semantic and BM25 search with cross-encoder reranking
  • Markdown-aware document chunking and category filters
  • Local FastEmbed ONNX indexing and retrieval
  • Document add, update, removal, and URL ingestion tools
  • Background reindexing with progress reporting
  • Retrieval evaluation with MRR@5 and Recall@5

Tools13

What Knowledge Rag lets your agent do. Expand a tool for its parameters.

Verified live~3.6k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

8/8 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · knowledge-rag (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars300Stargazers on the source repository.
Last commit1d agoMost recent push to the default branch.
Tools exposed13Callable tools this server registers over MCP.
Directory activity10 viewsConfig copies, upvotes, and views on AllMCPs.

How Knowledge Rag works

What lyonzin/knowledge-rag does

lyonzin/knowledge-rag provides a local retrieval-augmented knowledge base through MCP. It indexes files placed in a documents directory, stores their searchable chunks, and returns matching content with source paths and relevance scores. Supported categories include security, ctf, logscale, development, general, redteam, and blueteam.

The primary retrieval path combines semantic search with BM25 keyword matching and cross-encoder reranking. Search parameters control the balance between conceptual matching and exact terms, result count, minimum score, category, snippets, and search dispatch. This makes it suitable for both natural-language questions and identifiers such as CVE numbers or tool names.

How it works

Embedding generation, indexing, and retrieval run locally using FastEmbed ONNX. After the initial model download, the server can operate without external services. A local corpus can be populated from files, raw text, or publicly accessible web pages. URL ingestion makes an outbound HTTPS request, converts page content to Markdown, saves it, and indexes it.

Search results normally contain chunks rather than complete files. Once a relevant filepath is known, get_document returns the full document and metadata. search_similar uses an indexed document as the reference for finding related documents. The server can also report category counts, index health information, and retrieval metrics such as MRR@5 and Recall@5.

Setup and configuration

Install the Python package and initialize a workspace:

Terminal
pip install knowledge-rag
knowledge-rag init

Place Markdown, PDF, or code files in the generated documents/ directory, then restart the MCP client. Python 3.11 or newer is supported, and the project targets Windows, Linux, and macOS. No Docker, Ollama instance, or separate embedding server is required.

The server supports stdio for a client-owned process and SSE or streamable HTTP for shared deployments. HTTP configuration can set the host, port, bearer token, rate limiting, Prometheus metrics, and JSON logging. Streamable HTTP clients can connect to the /mcp endpoint; health and metrics endpoints are also available for HTTP deployments.

Tools and capabilities

  • Search with semantic, BM25, hybrid, or FTS5 dispatch, optional category filtering, score thresholds, and snippets.
  • Retrieve complete indexed documents by filepath and browse documents or category counts.
  • Add text, update existing files, remove index entries, or optionally delete files from disk.
  • Fetch public web pages, convert them to Markdown, and index them immediately.
  • Find documents similar to an indexed reference document.
  • Start background indexing, resume interrupted work, rebuild indexes, and poll reindex progress.
  • Inspect index statistics and test retrieval quality against expected filepaths.

Documents added or updated through the MCP tools become searchable immediately. Files changed outside those tools can be handled with a smart reindex; a full rebuild is intended for embedding-model changes or index corruption.

Limitations and notes

Search parameters and filepaths must refer to the indexed corpus. get_document requires a known indexed path, while search_similar also requires its reference document to be indexed. Removing a file from the index does not delete it unless the destructive delete_file option is enabled.

Local retrieval does not mean every operation is network-free: the initial model download and URL ingestion use network access, and MCP clients receive the retrieved content. HTTP deployments should therefore be configured with appropriate transport and access controls.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Knowledge Rag

lyonzin/knowledge-rag is an MCP server that connects AI clients to a local indexed document collection. Its main tools search knowledge with hybrid semantic and BM25 retrieval, fetch complete documents, manage files, discover similar documents, monitor indexing, and evaluate retrieval quality. Embeddings and retrieval run locally after model setup.

Install it with `pip install knowledge-rag`, then run `knowledge-rag init` to create the configuration and documents directory. Add files to that directory and restart the MCP client. Python 3.11 or newer is supported, and no Docker, Ollama, or separate embedding service is required.

Yes, lyonzin/knowledge-rag supports Cursor through MCP. It can run as a client-owned stdio process or as a streamable HTTP server shared by multiple clients. For the shared mode, start the server with streamable HTTP and point Cursor at the `/mcp` endpoint.

Yes, indexing and retrieval run locally and can work offline after the embedding model has been downloaded. The first model download needs network access, and `add_from_url` also requires outbound internet access to fetch a publicly accessible HTTPS page.

Use `add_document` for raw text, place files in the documents directory, or use `add_from_url` for a public web page. `add_document` and URL ingestion save and index content immediately. Use `update_document` to replace an existing file and `reindex_documents` for filesystem changes made outside the tools.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewKnowledge Rag AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/lyonzin-knowledge-rag?style=directory)](https://allmcps.com/mcp/lyonzin-knowledge-rag)
HTML Embed
<a href="https://allmcps.com/mcp/lyonzin-knowledge-rag"><img src="https://allmcps.com/api/badge/lyonzin-knowledge-rag?style=directory" alt="Knowledge Rag on AllMCPs" /></a>