Gnosis MCP is a documentation search server for AI agents, exposing tools and resources through the MCP (Model Context Protocol) protocol. Its core goal is to replace the practice of "pasting files directly into context" by letting AI agents search locally indexed documents when they need information, returning ranked and highlighted excerpt snippets, thereby significantly reducing the tokens consumed per query.
Main capabilities:
- Zero configuration: uses SQLite by default, and runs right after pip installation; PostgreSQL can be switched to automatically via GNOSIS_MCP_DATABASE_URL.
- Hybrid search: combines keyword search (BM25) with semantic search (local ONNX embeddings, no API key required), using RRF fusion, tunable via GNOSIS_MCP_RRF_K.
- Optional cross-encoder reranking: requires installing the [reranking] extra dependency, off by default; official testing found that the bundled MS-MARCO reranker degrades retrieval effectiveness on developer documentation, so it is recommended to test it first on your own corpus.
- Document ingestion: supports Markdown, .txt, .ipynb, .toml, .csv, .json, optionally .rst and .pdf; supports Git commit history (ingest-git) and web crawling (via sitemap or link crawling).
- Automatic linking: relates_to in frontmatter can create a navigable document graph.
- Watch mode: automatically re-ingests when files change.
- Cleaning up stale documents: gnosis-mcp ingest --prune deletes chunks whose source files no longer exist, and --wipe resets the entire index.
- Built-in evaluation tool: gnosis-mcp eval outputs Hit@K / MRR / Precision@K with a single command (based on bundled fixed samples, it is a smoke test, not a measurement against the user's corpus).
- Token savings tracking: gnosis-mcp savings lets you view savings; gnosis-mcp usage lets you view query statistics, missed queries, most frequently accessed documents, and more.
How to use:
- Installation: after pip install, the SQLite default configuration is ready to use.
- Enabling semantic search: add local embeddings, no API key required, automatically downloads about on first run 23 MB quantized model (MongoDB/mdbr-leaf-ir, Apache 2.0).
- Connecting clients: provides copy-paste JSON configurations for MCP clients such as Claude Code, Claude Desktop, Cursor, Zed, opencode, Windsurf, VS Code, JetBrains, Cline, etc. (see llms-install.md). The setup command can be used to automatically install the configuration for clients, and the doctor command checks whether clients are actually calling the server.
- Docker: provides multi-architecture images, about 140 MB, with built-in local ONNX embeddings and a REST interface, and includes docker-compose.yaml.
- Checks: gnosis-mcp check verifies that the backend starts and the required schema exists; keyword search relies on SQLite FTS5.
Use cases:
- Want AI coding assistants to retrieve based on local development documentation, API documentation, design decision records, etc., rather than hallucinating API signatures.
- Teams or individuals who need to quickly search across hundreds of files and reduce token consumption.
- Need a fully local documentation retrieval solution with no cloud dependency.
Limitations and notes:
- The bundled evaluation fixed sample returns the same numbers and is not a real measurement of user corpora; you need to evaluate your own corpus using tests/bench/bench_real_corpus.py.
- The reranker is disabled by default because in practice it significantly degrades retrieval quality on development documentation and increases latency.
- Semantic search requires an additional installed embedding model, and the first run needs to download about a 23 MB model.
- Write tools (three in total) are not exposed by default and require setting GNOSIS_MCP_WRITABLE=true.
- Access logging is enabled by default and can be disabled by setting GNOSIS_MCP_ACCESS_LOG=false.
- Specific performance numbers (such as 8.7 ms MCP round trip, hybrid search p50 < 30 ms, Hit@5=0.92, etc.) come from public benchmarks described in the official documentation, and actual results need to be verified on your own corpus.
Information not currently provided: specific pricing model, commercial support, SLA, etc. are not clearly stated in the materials.
