gnosis-mcp 0.11.3

Zero-config MCP server for searchable documentation (SQLite default, PostgreSQL optional)

Gnosis MCP

Turn your docs into a searchable knowledge base for AI agents.
pip install, ingest, serve.

Quick Start · Git History · Web Crawl · Backends · Editors · Tools · Embeddings · 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 to 8,000+ tokens each
• Architecture decisions buried across dozens of files

With Gnosis MCP

• search_docs returns ranked, highlighted excerpts (~600 tokens)
• Real answers grounded in your actual documentation
• Works across hundreds of docs instantly

---

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
• PostgreSQL ready — pgvector + tsvector when you need scale

Quick Start

pip 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

Run with Docker (zero install)

Multi-arch image, ~140 MB, ships with local ONNX embeddings + REST:

# Serve your ./docs on http://localhost:8000 — MCP at /mcp, REST at /api/*
docker run -p 8000:8000 \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest

# First-run: ingest into the persistent volume
docker run --rm \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest \
  ingest /docs --embed

Or use the committed docker-compose.yaml:

docker compose up -d
docker compose exec gnosis gnosis-mcp ingest /docs --embed

Images tagged :latest, :<version>, :<version-minor>, :main, :sha-<sha>.

Try without installing (uvx)

uvx gnosis-mcp ingest ./docs/
uvx gnosis-mcp serve

Web Crawl

_{Dry-run discovery → Crawl & ingest → Search crawled docs → SSRF protection}

Ingest docs from any website — no local files needed:

pip install gnosis-mcp[web]

# Crawl via sitemap (best for large doc sites)
gnosis-mcp crawl https://docs.stripe.com/ --sitemap

# Depth-limited link crawl with URL filter
gnosis-mcp crawl https://fastapi.tiangolo.com/ --depth 2 --include "/tutorial/*"

# Preview what would be crawled
gnosis-mcp crawl https://docs.python.org/ --dry-run

# Force re-crawl + embed for semantic search
gnosis-mcp crawl https://docs.sveltekit.dev/ --sitemap --force --embed

Respects robots.txt, caches with ETag/Last-Modified for incremental re-crawl, and rate-limits requests (5 concurrent, 0.2s delay). Crawled pages use the URL as the document path and hostname as the category — searchable like any other doc.

Git History

Turn commit messages into searchable context — your agent learns why things were built, not just what exists:

gnosis-mcp ingest-git .                                  # current repo, all files
gnosis-mcp ingest-git /path/to/repo --since 6m           # last 6 months only
gnosis-mcp ingest-git . --include "src/*" --max-commits 5 # filtered + limited
gnosis-mcp ingest-git . --dry-run                         # preview without ingesting
gnosis-mcp ingest-git . --embed                           # embed for semantic search

Each file's commit history becomes a searchable markdown document stored as git-history/<file-path>. The agent finds it via search_docs like any other doc — no new tools needed. Incremental re-ingest skips files with unchanged history.

Editor Integrations

Add the server config to your editor — your AI agent gets search_docs, get_doc, and get_related tools automatically:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Editor	Config file
Claude Code	.claude/mcp.json (or install as plugin)
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
JetBrains	Settings > Tools > AI Assistant > MCP Servers
Cline	Cline MCP settings panel

VS Code (GitHub Copilot) — slightly different key

Add to .vscode/mcp.json (note: "servers" not "mcpServers"):

{
  "servers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Also discoverable via the VS Code MCP gallery — search @mcp gnosis in the Extensions view.

Transport: Stdio vs HTTP

Gnosis supports two MCP transports. Which one you pick changes how sessions connect:

	Stdio (default)	Streamable HTTP
Start	gnosis-mcp serve	gnosis-mcp serve --transport streamable-http
Connection	One parent process owns stdin/stdout	Any number of clients connect via HTTP
Sharing	1:1 — each editor/session spawns its own server	N:1 — one server, many sessions
State	DB, file watcher, embeddings per-process	Shared across all clients
Best for	Single editor, quick start	Multiple terminals, CI/CD, remote access

Why this matters: Gnosis maintains persistent state — a SQLite/PostgreSQL database, an embedding cache, and (with --watch) a file system watcher. With stdio, each editor session spawns a separate server process with its own state. With HTTP, you start the server once and every session shares the same database and watcher.

For AI coding tools that open multiple sessions (e.g., Claude Code with agent teams, or parallel terminal tabs), HTTP avoids duplicate processes and keeps all sessions reading from the same index:

{
  "mcpServers": {
    "docs": {
      "type": "url",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Start the server separately (or via systemd/Docker):

gnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000

Stdio MCP servers like @modelcontextprotocol/server-postgres are stateless proxies — they forward a SQL query and return results, so per-session spawning is fine. Gnosis is stateful, which is why HTTP transport is the better choice for multi-session setups.

REST API

v0.10.0+ — Enable native HTTP endpoints alongside MCP on the same port.

gnosis-mcp serve --transport streamable-http --rest

Web apps can now query your docs over plain HTTP — no MCP protocol required.

Endpoint	Description
GET /health	Server status, version, doc count
GET /api/search?q=&limit=&category=	Search docs (auto-embeds with local provider)
GET /api/docs/{path}	Get document by file path
GET /api/docs/{path}/related	Get related documents
GET /api/categories	List categories with counts
GET /api/context?topic=&limit=&category=	Usage-weighted context summary
GET /api/graph/stats?category=	Knowledge graph topology

Environment variables:

Variable	Description
GNOSIS_MCP_REST=true	Enable REST API (same as --rest)
GNOSIS_MCP_CORS_ORIGINS	CORS allowed origins: * or comma-separated list
GNOSIS_MCP_API_KEY	Optional Bearer token auth (timing-safe comparison)
GNOSIS_MCP_PUBLIC_PATHS	Comma-separated auth-bypass paths. /health is always public.

Examples:

# Health check
curl http://127.0.0.1:8000/health

# Search
curl "http://127.0.0.1:8000/api/search?q=authentication&limit=5"

# With API key
curl -H "Authorization: Bearer sk-secret" "http://127.0.0.1:8000/api/search?q=setup"

Backends

	SQLite (default)	SQLite + embeddings	PostgreSQL
Install	pip install gnosis-mcp	pip install gnosis-mcp[embeddings]	pip install gnosis-mcp[postgres]
Config	Nothing	Nothing	Set GNOSIS_MCP_DATABASE_URL
Search	FTS5 keyword (BM25)	Hybrid keyword + semantic (RRF)	tsvector + pgvector hybrid
Embeddings	None	Local ONNX (23MB, no API key)	Any provider + HNSW index
Multi-table	No	No	Yes (UNION ALL)
Best for	Quick start, keyword-only	Semantic search without a server	Production, large doc sets

Auto-detection: Set GNOSIS_MCP_DATABASE_URL to postgresql://... and it uses PostgreSQL. Don't set it and it uses SQLite. Override with GNOSIS_MCP_BACKEND=sqlite|postgres.

PostgreSQL setup

pip install gnosis-mcp[postgres]
export GNOSIS_MCP_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
gnosis-mcp init-db              # create tables + indexes
gnosis-mcp ingest ./docs/       # load your markdown
gnosis-mcp serve

For hybrid semantic+keyword search, also enable pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

Then backfill embeddings:

gnosis-mcp embed                        # via OpenAI (default)
gnosis-mcp embed --provider ollama      # or use local Ollama

Claude Code Plugin

For Claude Code users, install as a plugin to get the MCP server plus slash commands:

claude plugin marketplace add nicholasglazer/gnosis-mcp
claude plugin install gnosis

This gives you:

Component	What you get
MCP server	gnosis-mcp serve — auto-configured, search tools in every chat
/gnosis:setup	First-time wizard: install → init-db → ingest → wire your editor
/gnosis:ingest	Bulk ingest (files, git history, web crawl) + re-ingest + prune
/gnosis:search	Keyword / hybrid / git-history search, formatted output
/gnosis:manage	Single-file CRUD — add, delete, update metadata
/gnosis:tune	Chunk-size sweep against your own golden queries
/gnosis:eval	Single-shot retrieval quality check with baseline tracking
/gnosis:context	Usage-weighted topic primer for session startup
/gnosis:status	Connectivity, schema, corpus health diagnostic
5 subagents	doc-explorer, doc-keeper, corpus-sync, context-loader, doc-reviewer

The plugin works with both SQLite and PostgreSQL backends. Prefer manual copy-paste over the plugin marketplace? See llms-install.md Path B.

Manual setup (without plugin)

Add to .claude/mcp.json:

{
  "mcpServers": {
    "gnosis": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

For PostgreSQL, add "env": {"GNOSIS_MCP_DATABASE_URL": "postgresql://..."}.

Tools & Resources

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

How search works

# Keyword search — works on both SQLite and PostgreSQL
gnosis-mcp search "stripe webhook"

# Hybrid search — keyword + semantic (requires [embeddings] or pgvector)
gnosis-mcp search "how does billing work" --embed

# Filtered — narrow results to a specific category
gnosis-mcp search "auth" -c guides

When called via MCP, the agent passes a query string for keyword search. With embeddings configured, search automatically combines keyword and semantic results using Reciprocal Rank Fusion. Results include a highlight field with matched terms in <mark> tags.

Context Loading

The get_context tool provides usage-weighted document summaries — ideal for session startup or "what matters most?" queries.

# Most-accessed docs (no topic)
get_context(limit=10)

# Topic-focused with access enrichment
get_context(topic="deployment", category="guides")

Behind the scenes, Gnosis tracks which documents are accessed via search_docs and get_doc, then uses access frequency to rank importance. Disable tracking with GNOSIS_MCP_ACCESS_LOG=false.

Graph & Links

Gnosis automatically extracts links from your documentation — both frontmatter relates_to declarations and markdown links in content. Use the graph tools to explore connections:

# Direct neighbors
get_related("guides/auth.md")

# Multi-hop traversal (2 levels deep, with titles)
get_related("guides/auth.md", depth=2, include_titles=True)

# Filter out noisy git history links
get_related("guides/auth.md", relation_type="relates_to")

# Graph topology: find orphans and hubs
get_graph_stats()

Relation types: related (default frontmatter), content_link (body markdown links + [[wikilinks]]), git_co_change (commit co-occurrence), git_ref (git history → source file). Plus 16 typed edges via the relations: frontmatter block: prerequisite, depends_on, summarizes / summarized_by, extends / extended_by, replaces / replaced_by, audited_by / audits, implements / implemented_by, tests / tested_by, example_of, references.

Embeddings

Embeddings enable semantic search — finding docs by meaning, not just keywords.

Local ONNX (recommended) — zero-config, no API key:

pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed       # ingest + embed in one step
gnosis-mcp embed                        # or embed existing chunks separately

Uses MongoDB/mdbr-leaf-ir (~23MB quantized, Apache 2.0). Auto-downloads on first run.

Remote providers — OpenAI, Ollama, or any OpenAI-compatible endpoint:

gnosis-mcp embed --provider openai      # requires GNOSIS_MCP_EMBED_API_KEY
gnosis-mcp embed --provider ollama      # uses local Ollama server

Pre-computed vectors — pass embeddings to upsert_doc or query_embedding to search_docs from your own pipeline.

Configuration

All settings via environment variables. Nothing required for SQLite — it works with zero config.

Variable	Default	Description
GNOSIS_MCP_DATABASE_URL	SQLite auto	PostgreSQL URL or SQLite file path
GNOSIS_MCP_BACKEND	auto	Force sqlite or postgres
GNOSIS_MCP_WRITABLE	false	Enable write tools
GNOSIS_MCP_TRANSPORT	stdio	Transport: stdio, sse, or streamable-http
GNOSIS_MCP_EMBEDDING_DIM	provider default	Vector dimension (OpenAI small: 1536; local ONNX: 384)

All configuration variables

Database: GNOSIS_MCP_SCHEMA (public), GNOSIS_MCP_CHUNKS_TABLE (documentation_chunks), GNOSIS_MCP_LINKS_TABLE (documentation_links), GNOSIS_MCP_SEARCH_FUNCTION (custom search on PG).

Search & chunking: GNOSIS_MCP_CONTENT_PREVIEW_CHARS (200), GNOSIS_MCP_CHUNK_SIZE (2000 — peak on real dev-docs corpus, bench-experiments), GNOSIS_MCP_SEARCH_LIMIT_MAX (20), GNOSIS_MCP_MAX_QUERY_CHARS (10000), GNOSIS_MCP_MAX_DOC_BYTES (50_000_000), GNOSIS_MCP_RRF_K (60).

Connection pool (PostgreSQL): GNOSIS_MCP_POOL_MIN (1), GNOSIS_MCP_POOL_MAX (3).

Webhooks: GNOSIS_MCP_WEBHOOK_URL, GNOSIS_MCP_WEBHOOK_TIMEOUT (5s), GNOSIS_MCP_WEBHOOK_ALLOW_PRIVATE (false — SSRF-guarded by default).

Embeddings: GNOSIS_MCP_EMBED_PROVIDER (openai/ollama/custom/local), GNOSIS_MCP_EMBED_MODEL, GNOSIS_MCP_EMBED_DIM (provider default), GNOSIS_MCP_EMBED_API_KEY, GNOSIS_MCP_EMBED_URL, GNOSIS_MCP_EMBED_BATCH_SIZE (50).

Reranking: GNOSIS_MCP_RERANK_ENABLED (false — requires [reranking] extra).

Web crawl: GNOSIS_MCP_CRAWL_EXTRACT_TIMEOUT_S (30s).

REST API: GNOSIS_MCP_REST (false), GNOSIS_MCP_API_KEY, GNOSIS_MCP_CORS_ORIGINS, GNOSIS_MCP_PUBLIC_PATHS (comma-separated allowlist — /health is always public), GNOSIS_MCP_HOST (127.0.0.1), GNOSIS_MCP_PORT (8000).

Access log: GNOSIS_MCP_ACCESS_LOG (true — tracks doc access for get_context).

Column overrides: GNOSIS_MCP_COL_FILE_PATH, GNOSIS_MCP_COL_TITLE, GNOSIS_MCP_COL_CONTENT, GNOSIS_MCP_COL_CHUNK_INDEX, GNOSIS_MCP_COL_CATEGORY, GNOSIS_MCP_COL_AUDIENCE, GNOSIS_MCP_COL_TAGS, GNOSIS_MCP_COL_EMBEDDING, GNOSIS_MCP_COL_TSV, GNOSIS_MCP_COL_SOURCE_PATH, GNOSIS_MCP_COL_TARGET_PATH, GNOSIS_MCP_COL_RELATION_TYPE.

Logging: GNOSIS_MCP_LOG_LEVEL (INFO).

Custom search function (PostgreSQL)

Delegate search to your own PostgreSQL function for custom ranking:

CREATE FUNCTION my_schema.my_search(
    p_query_text text,
    p_categories text[],
    p_limit integer
) RETURNS TABLE (
    file_path text, title text, content text,
    category text, combined_score double precision
) ...

GNOSIS_MCP_SEARCH_FUNCTION=my_schema.my_search

Multi-table mode (PostgreSQL)

Query across multiple doc tables:

GNOSIS_MCP_CHUNKS_TABLE=documentation_chunks,api_docs,tutorial_chunks

All tables must share the same schema. Reads use UNION ALL. Writes target the first table.

CLI reference

gnosis-mcp ingest <path> [--dry-run] [--force] [--embed] [--prune] [--wipe] [--include-crawled]
gnosis-mcp ingest-git <repo> [--since] [--until] [--author] [--max-commits-per-file]
                             [--include] [--exclude] [--include-merges]
                             [--dry-run] [--force] [--embed]
gnosis-mcp crawl <url> [--sitemap] [--max-depth N] [--include] [--exclude] [--max-pages N]
                       [--dry-run] [--force] [--embed]
gnosis-mcp serve [--transport stdio|sse|streamable-http] [--host HOST] [--port PORT]
                 [--ingest PATH] [--watch PATH] [--rest]
gnosis-mcp search <query> [-n LIMIT] [-c CAT] [--embed]    Search docs
gnosis-mcp stats                                           Document, chunk, and embedding counts
gnosis-mcp check                                           Verify DB connection + extensions
gnosis-mcp embed [--provider P] [--model M] [--batch-size N] [--dry-run]
gnosis-mcp init-db [--dry-run]                             Create tables + indexes
gnosis-mcp export [-f json|markdown] [-c CAT]              Export documents
gnosis-mcp diff <path>                                     Preview changes on re-ingest
gnosis-mcp prune <path> [--dry-run] [--include-crawled]    Delete chunks for missing files
gnosis-mcp cleanup [--days N]                              Purge old access log entries
gnosis-mcp eval [--json]                                   Retrieval quality harness (Hit@5, MRR, P@5)
gnosis-mcp fix-link-types                                  Migrate pre-0.10 git-history links

How ingestion works

gnosis-mcp ingest scans a directory for supported files and loads them into the database:

• Multi-format — Markdown native; .txt, .ipynb, .toml, .csv, .json auto-converted. Optional: .rst ([rst] extra), .pdf ([pdf] extra)
• Smart chunking — splits by H2 headings (H3/H4 for oversized sections), never splits inside code blocks or tables
• Frontmatter — extracts title, category, audience, tags from YAML frontmatter
• Auto-linking — relates_to in frontmatter creates bidirectional links for get_related
• Auto-categorization — infers category from parent directory name
• Incremental — content hashing skips unchanged files (--force to override)
• Watch mode — gnosis-mcp serve --watch ./docs/ auto-re-ingests on changes

Architecture

src/gnosis_mcp/
├── backend.py         DocBackend protocol + create_backend() factory
├── pg_backend.py      PostgreSQL — asyncpg, tsvector, pgvector
├── sqlite_backend.py  SQLite — aiosqlite, FTS5, sqlite-vec hybrid search (RRF)
├── sqlite_schema.py   SQLite DDL — tables, FTS5, triggers, vec0 virtual table
├── config.py          Config from env vars, backend auto-detection
├── db.py              Backend lifecycle + FastMCP lifespan
├── server.py          FastMCP server — 9 tools, 3 resources, auto-embed queries
├── ingest.py          File scanner + converters — multi-format, smart chunking
├── crawl.py           Web crawler — sitemap/BFS, robots.txt, ETag caching
├── parsers/           Non-file ingest sources (git history, future: schemas)
│   └── git_history.py Git log → markdown documents per file
├── watch.py           File watcher — mtime polling, auto-re-ingest
├── schema.py          PostgreSQL DDL — tables, indexes, search functions
├── embed.py           Embedding providers — OpenAI, Ollama, custom, local ONNX
├── local_embed.py     Local ONNX embedding engine — HuggingFace model download
└── cli.py             CLI — serve, ingest, crawl, search, embed, stats, check, cleanup

Available On

MCP Registry (feeds VS Code MCP gallery and GitHub Copilot) · PyPI · mcp.so · Glama · cursor.directory

AI-Friendly Docs

File	Purpose
llms.txt	Quick overview — what it does, tools, config
llms-full.txt	Complete reference in one file
llms-install.md	Step-by-step installation guide

Performance

Four questions, four measurements. Methodology, raw numbers, and reproduction commands: docs/benchmarks.md · full write-up at gnosismcp.com/#numbers.

1. Fast enough for agents. 8.7 ms mean, 13 ms p95 per MCP tool call (stdio round-trip). An agent calling search_docs twenty times in a response adds under a quarter-second.

2. Scales past the laptop. SQLite FTS5 keyword, median of 3 runs, in-memory:

Corpus	QPS	p95
100 docs	9,463	0.16 ms
1,000 docs	2,768	0.72 ms
5,000 docs	839	3.0 ms
10,000 docs	471	5.6 ms

3. Finds the right answer. Two corpora, two stories:

• Real developer docs (558 docs, 25 hand-written golden queries): Hit@5 = 0.92, nDCG@10 = 0.87, MRR = 0.79. v0.11 moved nDCG@10 from 0.8407 → 0.8702 by lowering the default GNOSIS_MCP_CHUNK_SIZE from 4000 → 2000 chars — peak of a 7-point sweep (full write-up).
• BEIR SciFact (5,183 docs, 300 test queries — public retrieval benchmark): nDCG@10 = 0.671. Within 1 % of the Lucene BM25 reference baseline (0.679) that hybrid and dense retrievers historically struggle to beat on this dataset.

4. Reproducible in one second. gnosis-mcp eval runs the small internal RAG eval locally:

$ gnosis-mcp eval
  Hit Rate@5:       1.000
  MRR:              0.950
  Mean Precision@5: 0.668

uv run python tests/bench/bench_search.py           # speed, scale curve
uv run python tests/bench/bench_rag.py              # quality, keyword vs hybrid
uv run python tests/bench/bench_mcp_e2e.py          # protocol round-trip
uv run python tests/bench/bench_real_corpus.py      # real-world retrieval on your own corpus

Install size: ~23 MB with [embeddings] (ONNX model). Base install is ~5 MB. Test suite: 632 tests — most run without a database.

Reranker warning. The bundled [reranking] extra stays off by default. On real dev-docs the MS-MARCO cross-encoder drops nDCG@10 by 27 points and adds 400× latency; BGE-reranker-v2-m3 drops it by 31 points at 2400× latency. Test on your corpus first. Full bench in bench-experiments-2026-04-18.

Development

git clone https://github.com/nicholasglazer/gnosis-mcp.git
cd gnosis-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                    # 632 tests, no database needed
ruff check src/ tests/

All tests run without a database. Keep it that way.

Good first contributions: new embedding providers, export formats, ingestion for new file types (via optional extras). Open an issue first for larger changes.

Sponsors

If Gnosis MCP saves you time, consider sponsoring the project.

License

MIT