Gnosis MCP

io.github.nicholasglazer由 GitHub 账号 nicholasglazer 发布v0.17.5更新于 Oct 25, 2026

Zero-config MCP server for searchable documentation. SQLite or PostgreSQL.

已验证STDIO仅桌面网页搜索与抓取知识与记忆

概览

AI 生成的概览

一个本地零配置的 MCP 服务器，把你自己的文档索引到 SQLite 或 PostgreSQL，让助手搜索文档而不是整份读取文件。

可以做什么
按关键词或语义加关键词的混合方式搜索文档，返回带高亮的摘录并统计节省的 token。按路径读取完整文档、沿关联和链接查找相关文档，并查看知识图谱统计。搜索已索引的 git 提交历史，获取按使用频率加权的上下文摘要。仅在开启写入模式时创建、替换、删除文档并修改其元数据。
适用场景
适合助手需要反复从本地文档库（如 API 参考、架构说明或项目文档）中找答案，并希望得到有依据、比粘贴文件更省 token 的回答。也适合希望对 git 历史或抓取的文档站点做检索的团队。
运行要求
作为本地 Python 进程运行，可从 PyPI 安装（pip 或 uvx），也可用 Docker 镜像。默认使用 SQLite，无需配置；PostgreSQL 加 pgvector 为可选项。关键词搜索需要 SQLite FTS5。语义搜索需要可选的 embeddings 附加组件；本地 ONNX 模型首次运行时下载，OpenAI 等远程提供方需要 GNOSIS_MCP_EMBED_API_KEY。配置通过 GNOSIS_MCP_* 环境变量完成。
安装前请注意
写入工具（upsert_doc、delete_doc、update_metadata）仅在 GNOSIS_MCP_WRITABLE 设为 true 时才会暴露，且会修改索引。prune 和 wipe 命令会删除已索引的分块，建议先用 dry-run 预览。访问日志默认记录查询和被检索的文档，可用 GNOSIS_MCP_ACCESS_LOG=false 关闭。GNOSIS_MCP_API_KEY 可选地保护 REST 端点。使用远程嵌入提供方时，文档文本会发送给该提供方。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Gnosis MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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.

[PyPI] [Downloads] [Python] [MIT License] [CI]

Quick Start · Documentation · Tools · Configuration · Full Reference

[Gnosis MCP — ingest docs, search, view stats, serve]
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 < 30 ms on a 700-doc corpus. Keyword QPS scales from 9,463 @ 100 docs to 471 @ 10,000 docs (full numbers).

Finds the right answer. On 558 real dev docs with 25 hand-written golden queries: Hit@5 = 0.92, nDCG@10 = 0.87, MRR = 0.79. On BEIR SciFact (5,183 docs, public retrieval benchmark): nDCG@10 = 0.671 — within 1 % of the Lucene BM25 baseline.

Tokens saved. Each search_docs call returns 200–500 tokens of on-point snippets instead of the 3,000–15,000 tokens a full-file Read would have cost. Track your own with gnosis-mcp savings (v0.12.0+) — the ledger writes to search_access_log on every call and aggregates per tool per --days N:

$ gnosis-mcp savings --days 7  Tool calls:               142  Tokens returned:        7,104  Tokens baseline:      231,580  Tokens saved:         224,476  Ratio:                   32.6×

Typical compression runs 10–60× depending on corpus coverage and query specificity — verify on yours. access_log is on by default; GNOSIS_MCP_ACCESS_LOG=false opts out.

The same ledger answers the other question — what is this corpus being asked, and where does it come up empty — with gnosis-mcp usage (v0.17.4+): calls, the queries that matched nothing, which documents are served most, which have never been served, and which clients are doing the asking.

Reproducible. gnosis-mcp eval runs a bundled retrieval-quality harness locally in one second — but it ingests nine hardcoded sample documents into a temporary database and answers ten bundled queries, so it returns the same numbers for every corpus and is a smoke test, not a measurement of your docs. To score your own corpus, run python tests/bench/bench_real_corpus.py --corpus <docs-root> --golden <golden.jsonl> (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

bash
pip install gnosis-mcp           # or: uv tool install gnosis-mcpgnosis-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 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.

Want semantic search? Add local embeddings — no API key needed:

bash
pip install gnosis-mcp[embeddings]gnosis-mcp ingest ./docs/ --embed   # ingest + embed in one stepgnosis-mcp serve                    # hybrid search auto-activated

Test it before connecting to an editor:

bash
gnosis-mcp check                                # FTS5 + schema + row counts; non-zero exit = stopgnosis-mcp search "getting started"             # keyword searchgnosis-mcp search "how does auth work" --embed  # hybrid semantic+keywordgnosis-mcp stats                                # see what was indexed

Then wire it into the clients you actually use — one command, no paths to edit:

bash
gnosis-mcp setup                # preview what each client's config would becomegnosis-mcp setup --write        # Claude Code, DeepSeek Harness, Codex, Cursor, VS Code, …gnosis-mcp doctor               # is it wired, and has anything called it yet?

setup resolves the command path for the machine it runs on instead of the one the README assumed, and each block it installs is marker-delimited so re-running rewrites it in place. Where a client does not read the server's own MCP instructions, it also installs the short rule that gives the agent a reason to prefer gnosis over reading files — a mounted server nobody calls is the silent failure mode. doctor is the check for that: it reads the access log and tells you whether a client has really called the server. Details: docs/cli.md.

gnosis-mcp check is the gate: it exits 0 only when the backend started and the schema the server needs is present, and it names whatever is missing before exiting 1. Keyword search needs SQLite FTS5, which is compiled into your Python's SQLite rather than guaranteed by it — check reports it as FTS5: ready. Anything else: docs/troubleshooting.md.

Run with Docker (zero install)

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

bash
# 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 volumedocker 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:

bash
docker compose up -ddocker compose exec gnosis gnosis-mcp ingest /docs --embed

Images tagged :latest, :<version>, :<version-minor>, :main, :sha-<sha>. Production recipes — systemd, reverse proxy, security checklist, upgrades — are in docs/deployment.md.

Try without installing (uvx)
bash
uvx gnosis-mcp ingest ./docs/uvx gnosis-mcp serve

Documentation

Canonical index — every topic is one hop away: docs/overview.md.

The handful most readers need:

Also in docs/: REST API · embeddings service · how we measure search · reranker experiments · releasing.

Tools

Gnosis MCP exposes nine tools and three resources over MCP. Your AI agent calls these automatically when it needs information from your docs:

ToolWhat it doesMode
search_docsSearch by keyword or hybrid semantic+keywordRead
get_docRetrieve a full document by pathRead
get_relatedFind linked/related documents (multi-hop, relation type filtering)Read
search_git_historySearch indexed git commit historyRead
get_contextUsage-weighted context summaryRead
get_graph_statsKnowledge graph topology: orphans, hubs, relation distributionRead
upsert_docCreate or replace a documentWrite
delete_docRemove a document and its chunksWrite
update_metadataChange title, category, tagsWrite

The six read tools are always advertised. The three write tools require GNOSIS_MCP_WRITABLE=true — without it they are withdrawn from tools/list entirely, so a read-only client is never handed a tool it cannot call.

Resource URIReturns
gnosis://docsAll documents — path, title, category, chunk count
gnosis://docs/{path}Full document content
gnosis://categoriesCategories with document counts

With embeddings configured, search_docs fuses keyword and semantic results with Reciprocal Rank Fusion and returns a highlight field carrying the matched terms in <mark> tags — that is what keeps a lookup at a few hundred tokens instead of a full file. get_context is the session-start tool: it ranks documents by how often they are actually retrieved, unless GNOSIS_MCP_ACCESS_LOG=false turns tracking off.

Full reference — every parameter, return shape, error, and the graph relation types (related, content_link, git_co_change, git_ref, plus the typed frontmatter edges): docs/tools.md.

Configuration

Nothing required for SQLite — zero config works. Override via GNOSIS_MCP_* env vars. The four most-asked:

VariableDefaultDescription
GNOSIS_MCP_DATABASE_URLSQLite autoPostgreSQL URL (backend auto-detects) or SQLite file path
GNOSIS_MCP_WRITABLEfalseEnable upsert_doc / delete_doc / update_metadata
GNOSIS_MCP_EMBED_PROVIDERunsetlocal turns on hybrid search (needs [embeddings] extra); or openai / ollama / custom
GNOSIS_MCP_API_KEYunsetOptional Bearer auth for every REST endpoint except /health

The remaining 45 — chunking, search limits, RRF, reranking, crawl, webhooks, column overrides, logging — are documented in docs/config.md.

Backend selection is automatic: set GNOSIS_MCP_DATABASE_URL to a postgresql:// URL and it uses PostgreSQL; leave it unset and it uses SQLite at ~/.local/share/gnosis-mcp/docs.db. Override with GNOSIS_MCP_BACKEND=sqlite|postgres. PostgreSQL setup — gnosis-mcp[postgres], gnosis-mcp init-db, CREATE EXTENSION IF NOT EXISTS vector, then gnosis-mcp embed — is in docs/overview.md.

Embeddings

Semantic search is the one optional add-on most setups want. Local ONNX is the recommended path: zero config, no API key, ~23 MB quantized model (MongoDB/mdbr-leaf-ir, Apache 2.0) auto-downloaded on first run.

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

Remote providers work the same way via gnosis-mcp embed --provider openai (needs GNOSIS_MCP_EMBED_API_KEY) or --provider ollama. Model choices, dimensions, the OpenAI-compatible POST /v1/embed service, and pre-computed vectors for your own pipeline: docs/embeddings-service.md · docs/config.md.

Available On

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

AI-Friendly Docs

FilePurpose
llms.txtQuick overview — what it does, tools, config
llms-full.txtComplete reference in one file
llms-install.mdStep-by-step installation guide

Development

bash
git clone https://github.com/nicholasglazer/gnosis-mcp.gitcd gnosis-mcppython -m venv .venv && source .venv/bin/activatepip install -e ".[dev]"pytest                    # 862 tests, no database neededruff 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

Learn more

来源：README.md，提交 8397bd0

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.17.5最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分