nicholasglazer/gnosis-mcp

Stop pasting files into context. Your AI agent searches your local docs instead. 5–10× fewer tokens per lookup. 92 % Hit@5 on real dev docs. Zero cloud dependencies.
Quick Start ·
Documentation ·
Tools ·
Configuration ·
Full Reference
Ingest docs → Search with highlights → Stats overview → Serve to AI agents
---
Without a docs server
- LLMs hallucinate API signatures that don't exist
- Entire files dumped into context — 3,000–15,000 tokens per doc
- Architecture decisions buried across dozens of files
- Every repeated lookup pays full context cost
With Gnosis MCP
- search_docs returns ranked, highlighted excerpts — typically 300–800 tokens
- Real answers grounded in your actual docs, not guesses from training data
- One local index across hundreds of files — instant multi-doc search
- **5–10× token savings** per lookup when your corpus covers the question
---
What makes gnosis-mcp different
- **Your data stays on your machine.** SQLite by default, PostgreSQL at scale — nothing leaves the host.
- **Index anything that's docs-shaped.** Markdown, git commit history, crawled websites — one index, one search API.
- **Measured, not marketed.** Ships BEIR SciFact numbers (0.671 nDCG@10 — within 1 % of the Lucene BM25 baseline), a reproducible eval harness (gnosis-mcp eval), and a chunk-size sweep showing where the quality plateau actually sits.
Full side-by-side vs Context7 / docs-mcp-server / mcp-local-rag: gnosismcp.com#compare.
---
Features
- **Zero config** — SQLite by default, pip install and go
- **Hybrid search** — keyword (BM25) + semantic (local ONNX embeddings, no API key). Tune RRF fusion with GNOSIS_MCP_RRF_K.
- **Cross-encoder reranking** — optional [reranking] extra with a 22M-param ONNX model. Off by default. **Test on your own corpus before enabling** — the bundled MS-MARCO reranker hurts dev-doc retrieval in our measurements.
- **Git history** — ingest commit messages as searchable context (ingest-git)
- **Web crawl** — ingest documentation from any website via sitemap or link crawl
- **Multi-format** — .md .txt .ipynb .toml .csv .json + optional .rst .pdf
- **Auto-linking** — relates_to frontmatter creates a navigable document graph
- **Watch mode** — auto-re-ingest on file changes
- **Prune stale docs** — gnosis-mcp ingest --prune removes chunks whose source file was deleted. --wipe for a full reset before re-ingest.
- **Built-in eval harness** — gnosis-mcp eval prints Hit@K / MRR / Precision@K in one command, against a bundled fixed fixture set
- **PostgreSQL ready** — pgvector + tsvector when you need scale
Performance
**Fast.** 8.7 ms mean MCP round-trip. Hybrid search p50 --golden (the numbers above come from tests/bench/golden-knowledge.jsonl). tests/bench/*.py reproduce every number. Methodology: docs/benchmarks.md.
**Rerankers stay off by default.** The bundled MS-MARCO cross-encoder drops nDCG@10 by 27 points on dev-docs and adds 400× latency; BGE-reranker-v2-m3 drops it 31 points at 2400×. Test on your corpus before enabling — full write-up: bench-experiments-2026-04-18.
Quick Start
That's it. Your AI agent can now search your docs.
**Connect your client** — see llms-install.md for copy-paste JSON snippets for Claude Code, Claude Desktop, Cursor, Zed, opencode, Windsurf, VS Code, JetBrains, Cline, and any other MCP client.
**Re-organized your docs?** gnosis-mcp ingest ./docs --prune re-ingests and removes any DB chunk whose source file no longer exists. --wipe resets the entire index first. Or run gnosis-mcp prune ./docs --dry-run to preview what would be deleted. Pruning only touches documents this root is responsible for: crawled URLs and generated documents (git history) are left alone unless --include-crawled / --include-generated says otherwise.