knowledge-rag MCP
A local MCP server that turns a folder of documents into a knowledge base with hybrid search for Claude Code and Cursor
- 300 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The add_document, update_document and remove_document tools change the index, and add_from_url fetches pages from the network
- The connected client receives snippets of your documents, and in network mode without a token anyone who can reach the port can read them
Install
- Works in
Manual install
pip install knowledge-ragThen knowledge-rag init creates config.yaml and the documents folder. Restart the MCP client.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The add_document, update_document and remove_document tools change the index, and add_from_url fetches pages from the network
- The connected client receives snippets of your documents, and in network mode without a token anyone who can reach the port can read them
This is third-party code. Review the repository files before installing.
What it does
knowledge-rag is an MCP server that turns a folder of documents into a knowledge base for an agent. Embeddings are computed locally through FastEmbed on ONNX, and storage is based on ChromaDB. No extra servers or API keys are needed. Search is hybrid: semantic similarity is combined with BM25, then a cross-encoder reranks the results. The agent gets 13 tools for search, editing the base and fetching pages by link. The evaluate_retrieval tool measures search quality with MRR@5, Recall@5 and Precision@5. By default the server runs over stdio for one client. For several clients it runs in streamable-http mode, with auth, rate limits and Prometheus metrics if needed. The repository also holds ten skills that teach the agent to check the base first, cite sources and write decisions back.
Who it is for. For developers and analysts who want to give Claude Code, Cursor or another MCP client search over their PDFs, Markdown and code without sending files to the cloud.
Good fit when
- You need search over internal docs, architecture decisions and references that sit in a folder on disk
- The agent must cite a source with a path and line, which the rag-cite-sources skill supports
- Several clients, such as Claude and Cursor, should share one index through streamable-http
- The network is air-gapped: the Docker image ships with preloaded models
- You want to measure search quality on your own corpus with the evaluate_retrieval tool
Not a fit when
- You need code search that understands calls and dependencies: the server indexes documents by text
- The corpus is huge and resources are tight: the first embedding model download is about 200 MB
- You need a managed cloud store: knowledge-rag is built for local installation
Example request
Search my knowledge base for every decision about the message queue and show sources with file pathsMCP
- Transport
- stdio, http, sse
- Authentication
- not required
Limitations
On the first query the server downloads an embedding model of about 200 MB, then works offline. The add_from_url tool uses the network, and fetched text goes to the client. Treat database content as untrusted data: the server offers weak protection against injections in documents. Claude Custom Connectors connect from Anthropic's cloud and cannot reach 127.0.0.1, so they need a public HTTPS address. HTTP modes use a single-instance lock, so two processes cannot share one data directory.
How to disable. Remove the knowledge-rag entry from the client's MCP configuration and run `pip uninstall knowledge-rag`. The index and documents live in project folders and can be deleted by hand.
FAQ
How do I connect knowledge-rag to Claude Code?
Run `pip install knowledge-rag`, then `knowledge-rag init`: it creates config.yaml and the documents folder. Put files there, restart Claude Code and call search_knowledge. The first query downloads the embedding model.
How do I make one server for several clients?
Run `knowledge-rag --transport streamable-http`. The endpoint is http://127.0.0.1:8179/mcp, so add it as a remote MCP server in each client.
How do I protect the network server?
In config.yaml under server set auth.bearer_token and set up HTTPS through a reverse proxy such as Caddy or Nginx. By default the server listens on 127.0.0.1. There is a /health address for health checks and a separate port for Prometheus metrics.
Which skills come with knowledge-rag?
Ten, for example rag-check-first, rag-cite-sources and rag-evaluate-quality. Install them with `npx skills add lyonzin/knowledge-rag` or the install.sh script with the `--project` and `--only` flags.
Do my documents go to the cloud?
No, embeddings, indexing and search run locally. The connected MCP client receives the retrieved snippets, and its model may run in the cloud.
Discussion
No questions or reviews yet.
Related
MCP serversA CLI and MCP server that extracts structured knowledge from documents: graphs, hypergraphs, and fact search with sources
On-premises RAG in containers with an MCP server: the agent searches your documents while data stays local
MCP Local RAG
mcp-local-rag
Local search over your documents, semantic and keyword, with no keys, Docker or external database. Works offline after the first model download
The official MCP server for the Chroma vector database: collections, documents, semantic and full-text search
A CLI engine that compiles documents into a local structured wiki: a transparent alternative to plain RAG, reachable by an agent over MCP
Official Pinecone MCP server: documentation search, index creation, record upserts and search from your agent
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| knowledge-rag (this entry) | no | not required | 300 | |
| VectorCode | no | not required | 874 | indexes repository code to find context; knowledge-rag works with documents of many formats and measures retrieval quality |
| M-flow | no | API key | 4,510 | an MCP memory server on a knowledge graph where relevance follows an evidence path; this uses classic hybrid BM25 plus vector search |
README in short
The README presents the project as local RAG with hybrid search and opens with a three-step quick start. Connection over stdio, HTTP and Docker, a tool table and an operations section follow.