Gnosis Mcp
About
Zero-config knowledge base for AI coding agents. Loads your markdown docs into a searchable database and exposes them as MCP tools — search, read, and manage documentation without leaving your editor. Works instantly with SQLite (no setup), upgrades to PostgreSQL + pgvector for hybrid semantic search. Includes skills…
Details
- License
- MIT
Explore
- 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
- PostgreSQL ready — pgvector + tsvector when you need scale
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Gnosis McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
pip install gnosis-mcp # or: uv tool install gnosis-mcp
gnosis-mcp ingest ./docs/ # loads docs into SQLite (auto-created)
gnosis-mcp serve # starts MCP server
That's it. Your AI agent can now search your docs.
Connect your editor — see llms-install.md for copy-paste JSON snippets for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, and Cline.
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.
Want semantic search? Add local embeddings — no API key needed:
pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed # ingest + embed in one step
gnosis-mcp serve # hybrid search auto-activated
Test it before connecting to an editor:
gnosis-mcp search "getting started" # keyword search
gnosis-mcp search "how does auth work" --embed # hybrid semantic+keyword
gnosis-mcp stats # see what was indexed
<details>
<summary>Run with Docker (zero install)</summary>
Multi-arch image, ~140 MB, ships with local ONNX embeddings + REST:
```bash
search_docs
Search by keyword or hybrid semantic+keyword
get_doc
Retrieve a full document by path
get_related
Find linked/related documents (multi-hop, relation type filtering)
search_git_history
Search indexed git commit history
get_context
Usage-weighted context summary
get_graph_stats
Knowledge graph topology: orphans, hubs, relation distribution
upsert_doc
Create or replace a document
delete_doc
Remove a document and its chunks
update_metadata
Change title, category, tags
Gnosis MCP exposes 9 tools and 3 resources over MCP. Your AI agent calls these automatically when it needs information from your docs.
| Tool | What it does | Mode |
|------|-------------|------|
| search_docs | Search by keyword or hybrid semantic+keyword | Read |
| get_doc | Retrieve a full document by path | Read |
| get_related | Find linked/related documents (multi-hop, relation type filtering) | Read |
| search_git_history | Search indexed git commit history | Read |
| get_context | Usage-weighted context summary | Read |
| get_graph_stats | Knowledge graph topology: orphans, hubs, relation distribution | Read |
| upsert_doc | Create or replace a document | Write |
| delete_doc | Remove a document and its chunks | Write |
| update_metadata | Change title, category, tags | Write |
Read tools are always available. Write tools require GNOSIS_MCP_WRITABLE=true.
| Resource URI | Returns |
|-----|---------|
| gnosis://docs | All documents — path, title, category, chunk count |
| gnosis://docs/{path} | Full document content |
| gnosis://categories | Categories with document counts |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"gnosis mcp": {
"gnosis": {
"command": "gnosis-mcp",
"args": [
"serve"
]
}
}
}
}McpServers
{
"gnosis": {
"command": "gnosis-mcp",
"args": [
"serve"
]
}
}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.
---
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
