search_docsLABSCO SUMMARY
Ships its own measurements, including the ones that did not go its way.
On the author's 558-document dev-docs corpus with 25 hand-written queries, Hit@5 is 0.92 and nDCG@10 is 0.87; on the public BEIR SciFact benchmark nDCG@10 is 0.671. More telling: reranking is off by default because the bundled cross-encoder measured 27 points of nDCG@10 worse on dev docs, and the README says so with a link to the experiment. The eval harness is a command you can run on your own corpus rather than a number you have to take on faith.
What it is
A self-hosted docs search server. You ingest directories, git commit history or crawled websites into SQLite or PostgreSQL, and the agent queries that index rather than pulling entire files into context. Embeddings run locally through ONNX, so semantic search needs no API key.
What you get
- 9 tools and 3 resources over MCP
- search_docs searches by keyword or by hybrid keyword-plus-semantic ranking, returning ranked excerpts with matched terms wrapped in mark tags
- get_doc returns a full document by path; get_related walks the link graph with multi-hop depth and relation-type filtering
- search_git_history searches indexed commit messages, so the agent can find out why something was built
- get_context returns a usage-weighted summary of what matters most, ranked by how often documents have actually been read
- get_graph_stats reports orphans, hubs and relation distribution across the corpus
- upsert_doc, delete_doc and update_metadata write back — gated behind GNOSIS_MCP_WRITABLE
- Resources at gnosis://docs, gnosis://docs/{path} and gnosis://categories expose the corpus directly
Requirements
The Python package gnosis-mcp, version 0.14.1, installed with pip or uv and started as gnosis-mcp serve; a container image and uvx also work. Nothing else is required — SQLite is created automatically. Semantic search needs the embeddings extra, which downloads a 23MB local model on first run. PostgreSQL is selected by setting GNOSIS_MCP_DATABASE_URL, and write tools stay off until GNOSIS_MCP_WRITABLE is true.
Setup effort
One command — pip install gnosis-mcp
USE CASES
01
Answering a question from your own docs
Ranked excerpts with the matched terms highlighted, instead of a whole file read into context.
02
Finding out why the code looks like this
Commit messages become searchable documents alongside the docs themselves.
03
Indexing a documentation site you do not own
Crawl via sitemap or depth-limited links, then search it like any other corpus.
04
Starting a session with the right context
A usage-weighted primer of the documents that actually get read.
05
Finding the gaps in your documentation
Graph statistics name the orphans and the hubs rather than describing the shape in prose.
9 tools
Listed in project docs. Your client may show a different list.
get_docget_relatedsearch_git_historyget_contextget_graph_statsupsert_docdelete_docupdate_metadataBEFORE YOU INSTALL
What to know first
Tools you get
9 tools named in the project's documentation.
Requires
gnosis-mcp on PATH
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install gnosis-mcpMCP Clients
Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"gnosis": {
"command": "gnosis-mcp",
"args": [
"serve"
]
}
}
}Cursor, Windsurf, JetBrains, Cline
JSON
{
"mcpServers": {
"docs": {
"command": "gnosis-mcp",
"args": [
"serve"
]
}
}
}VS Code
VS CODE · JSON
{
"servers": {
"docs": {
"command": "gnosis-mcp",
"args": [
"serve"
]
}
}
}Any MCP client — HTTP
Start one shared server over HTTP with gnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000, then point your client at it:
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"docs": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}Claude Code needs "type": "http" on this entry; the README's "type": "url" is not a transport value MCP clients accept.
Other routes
Run server in Docker
RUN SERVER IN DOCKER · TERMINAL
docker run -p 8000:8000 \
-v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
ghcr.io/nicholasglazer/gnosis-mcp:latest
