Context7 has 50,000 stars and indexes thousands of public libraries. It’s genuinely great — ask Claude what the SvelteKit load function signature looks like and Context7 will tell you, grounded in the actual docs.
But Context7 doesn’t know about your architecture decision records. Your internal API specs. The custom Temporal workflows your team spent six months building. The runbook that explains why the billing service restarts every 3 days.
That’s the problem gnosis-mcp solves.
What is gnosis-mcp?
gnosis-mcp is a zero-config MCP server that turns your own documentation into a searchable knowledge base for AI agents. Three commands and your agent can search hundreds of your own docs — not hallucinated summaries, not the entire file dumped into context, but ranked, highlighted excerpts grounded in what you actually wrote.
pip install gnosis-mcp
gnosis-mcp ingest ./docs/
gnosis-mcp serveThat’s it. Claude Code, Cursor, or any MCP-compatible client can now call search_docs against your documentation. A query returns ~600 tokens of relevant, highlighted content instead of forcing the LLM to reason over a 4,000-token raw file.
How does the search actually work?
gnosis-mcp uses hybrid search — BM25 keyword matching fused with local ONNX semantic embeddings — so it finds documents both by exact terms and by meaning. No API keys, no calls to OpenAI. The embedding model downloads once and runs locally.
Install the embeddings extra to activate it:
pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed
gnosis-mcp serveThe SQLite backend uses FTS5 with porter stemming for keyword search, and sqlite-vec for cosine similarity. Results from both passes merge via Reciprocal Rank Fusion — a technique that outperforms linear score blending when the two ranking signals have incompatible scales. The PostgreSQL backend does the same with tsvector + pgvector + HNSW indexing.
Searching for “authentication token expiry” returns chunks about JWT TTLs and session invalidation even if your docs use the word “expiration” instead of “expiry.” That’s semantic search earning its keep.
How does gnosis-mcp handle chunking?
Smart chunking prevents the problem where a 3,000-word document gets sliced at an arbitrary character count, bisecting a code block mid-function. gnosis-mcp splits on headings first — H2 as primary boundaries, H3/H4 for sections that would still be oversized — then falls back to paragraph breaks. It never splits inside fenced code blocks or tables.
Each chunk gets a SHA-256 hash. Re-ingesting a directory skips unchanged files, so a gnosis-mcp ingest run on 200 docs after editing 3 files only processes those 3. With watch mode, it does this automatically:
gnosis-mcp serve --watch ./docs/Edit a file, save it — the chunk is replaced within seconds.
How does gnosis-mcp compare to alternatives?
Context7 indexes public library documentation. gnosis-mcp indexes your private docs. They’re complementary — run both. Here’s how gnosis-mcp stacks up against other options in the private-docs space:
| Feature | gnosis-mcp | mcp-local-rag | Grounded Docs | LangChain RAG |
|---|---|---|---|---|
| Your own private docs | Yes | Yes | Yes | Yes |
| Zero config (pip + 2 commands) | Yes | Yes | Yes | No |
| Local embeddings (no API key) | ONNX | Yes | Requires provider | Requires provider |
| Hybrid search (keyword + semantic) | FTS5 + vec | Yes | Optional | Optional |
| PostgreSQL + HNSW backend | Yes | No | No | Plugin |
| Web crawling built-in | Yes | No | Yes | Plugin |
| Git history indexing | Yes | No | No | No |
| File watching (auto re-ingest) | Yes | No | No | No |
| REST API alongside MCP | Yes | No | No | N/A |
| Write tools (upsert / delete) | Yes | No | No | N/A |
| Link graph (get_related) | Yes | No | No | No |
| Content hashing (skip unchanged) | Yes | No | No | No |
| llms.txt + llms-full.txt | Yes | No | No | No |
| Dependencies | 2 | ~30+ | npm ecosystem | 50+ |
| Tests | 550+ | Unknown | Unknown | Separate |
The 2 dependencies figure is worth expanding: mcp>=1.20 and aiosqlite>=0.20. That’s the entire required footprint for the SQLite default setup. Optional extras like [embeddings], [postgres], and [web] add dependencies only if you actually need them.
LangChain solves this space too — but it solves it like installing a kitchen to make toast. If your docs fit in SQLite, you don’t need 50 transitive dependencies and a vector store abstraction layer.
What makes git history indexing different?
This is the feature that surprised me most when building it. Every codebase accumulates context in git commits that never makes it into documentation: why a table was restructured, what regression a particular fix addressed, which approach was tried and abandoned before the current solution.
gnosis-mcp ingest-git ./ # index commit history for this repoThe git parser groups commits by file, renders them as structured markdown, and ingests them through the same chunking pipeline as regular docs. When Claude Code asks “why does this service restart every 3 days,” it can now surface the commit from six months ago that explains the connection pool behavior — not because anyone wrote documentation, but because someone wrote a good commit message.
What backends does gnosis-mcp support?
gnosis-mcp ships with two backends: SQLite (default, zero-config) and PostgreSQL with pgvector.
SQLite is where you start. It requires nothing — no database server, no connection string, no init. The database lives at ~/.local/share/gnosis-mcp/docs.db (XDG-compliant). For most teams with a few hundred docs, it’s all you need.
PostgreSQL is where you scale. Switch by setting DATABASE_URL:
export DATABASE_URL=postgresql://localhost/mydb
gnosis-mcp init-db # creates tables, HNSW index
gnosis-mcp ingest ./docs/ --embed
gnosis-mcp serveThe PostgreSQL backend uses tsvector + websearch_to_tsquery for full-text search and pgvector with an HNSW index for sub-millisecond cosine similarity at scale. Both backends expose the same 6 tools to MCP clients — the choice of backend is invisible to your AI agent.
How does gnosis-mcp integrate with Claude Code and Cursor?
gnosis-mcp communicates over the Model Context Protocol, the open standard Anthropic shipped in late 2024. Any MCP-compatible client — Claude Code, Cursor, Cline, or a custom agent — can connect.
For Claude Code, add to your .mcp.json:
{
"mcpServers": {
"gnosis": {
"command": "gnosis-mcp",
"args": ["serve"]
}
}
}The server exposes 6 tools: search_docs, get_doc, get_related for reading, and upsert_doc, delete_doc, update_metadata for writing (gated behind GNOSIS_MCP_WRITABLE=true). It also exposes 3 resources: gnosis://docs (full document list), gnosis://docs/{path} (document content by path), and gnosis://categories.
A REST API runs alongside the MCP server if you need to query docs from a web UI or CI pipeline:
gnosis-mcp serve --rest
# GET http://localhost:8000/api/search?q=authenticationWhat’s in v0.10.6?
v0.10.6 is the 22nd release in five weeks. The pace reflects real-world feedback from teams using gnosis-mcp in production — each release closes something that was genuinely missing.
The 0.10.x series added the REST API, the diff command for auditing stale documentation, the --embed flag for single-pass ingest with embeddings, and the llms.txt / llms-full.txt resources for AI discoverability. The test suite crossed 550 tests this week. No database is required to run them — the unit tests exercise the chunker, parser, hash logic, and search ranking without touching aiosqlite.
The roadmap has three focuses: better multi-language support for non-English documentation, a hosted option for teams who don’t want to run the server themselves, and deeper editor integrations.
gnosis-mcp is MIT-licensed. Source at github.com/nicholasglazer/gnosis-mcp, installable from PyPI today.
If you’re already using Context7 for public library docs, gnosis-mcp is the missing half — the part that knows about your codebase.
pip install gnosis-mcp
gnosis-mcp ingest ./docs/
gnosis-mcp serve