Gnosis Mcp

本地服务

gnosismcp.com搜索与检索302 周前更新

代码仓库访问官网

关于 Gnosis Mcp

Gnosis MCP 是零配置的 MCP 服务，用于检索本地文档。默认使用 SQLite，可选 PostgreSQL，数据不离开本机，适合希望让 AI 智能体直接搜索文档而非粘贴文件的开发者。

主要功能

01零配置，默认使用 SQLite
02关键词与本地语义混合搜索
03可选的交叉编码器重排序
04支持 Git 提交历史与网站抓取内容导入
05文件变更监视与过期文档清理
06内置检索评估命令

适用场景

01让编码 Agent 直接检索本地项目文档
02将 Git 提交历史作为可搜索上下文索引
03为文档站点建立本地搜索索引

MCP 相关

作为 MCP 服务，它向 MCP 客户端暴露文档搜索、文档读取、关联文档查询等工具，并在启用时开放写入工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令uvx gnosis-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypignosis-mcp0.17.5stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Gnosis MCP

别再把文件粘贴到上下文中。让你的 AI Agent 搜索本地文档即可。
每次查找减少 5–10× 的 Token。真实开发文档 Hit@5 达到 92%。零云端依赖。

快速开始 · 文档 · 工具 · 配置 · 完整参考

_{导入文档 → 搜索并查看高亮内容 → 统计概览 → 提供给 AI Agent 使用}

没有文档服务时

大模型会臆造并不存在的 API 签名
整个文件被塞进上下文——每篇文档 3,000–15,000 个 Token
架构决策散落在数十个文件中
每次重复查找都要付出完整的上下文成本

使用 Gnosis MCP 后

search_docs 返回经过排序并带有高亮内容的摘录——通常为 300–800 个 Token
答案基于你的实际文档，而非训练数据中的猜测
一个本地索引覆盖数百个文件——即时搜索多篇文档
当语料库涵盖问题所需内容时，每次查找可节省 5–10× 的 Token

gnosis-mcp 的独特之处

数据始终留在你的设备上。 默认使用 SQLite，大规模部署时可使用 PostgreSQL——数据不会离开主机。
任何类似文档的内容都能建立索引。 Markdown、git 提交历史、爬取的网站——一个索引，一个搜索 API。
用实测数据说话，而非营销宣传。 提供 BEIR SciFact 数据（nDCG@10 为 0.671，与 Lucene BM25 基线相差不到 1 %）、可复现的评测工具（gnosis-mcp eval），以及展示质量实际趋于平稳位置的分块大小扫描。

与 Context7 / docs-mcp-server / mcp-local-rag 的完整对比：gnosismcp.com#compare。

特性

零配置 — 默认使用 SQLite，执行 pip install 即可运行
混合搜索 — 关键词（BM25）+ 语义搜索（本地 ONNX 嵌入，无需 API 密钥）。使用 GNOSIS_MCP_RRF_K 调整 RRF 融合。
交叉编码器重排 — 可选的 [reranking] 附加项，包含一个 22M 参数的 ONNX 模型。默认关闭。启用前请在自己的语料库上测试 — 根据我们的测量，附带的 MS-MARCO 重排器会降低开发文档检索效果。
Git 历史 — 将提交消息作为可搜索上下文导入（ingest-git）
网页爬取 — 通过站点地图或链接爬取，从任意网站导入文档
多格式支持 — .md .txt .ipynb .toml .csv .json + 可选的 .rst .pdf
自动关联 — relates_to frontmatter 可创建可浏览的文档图谱
监视模式 — 文件更改时自动重新导入
清理过期文档 — gnosis-mcp ingest --prune 会删除源文件已被删除的文档块。使用 --wipe 可在重新导入前彻底重置。
内置评估工具 — gnosis-mcp eval 可通过一条命令，针对附带的固定测试集输出 Hit@K / MRR / Precision@K
支持 PostgreSQL — 需要扩展规模时可使用 pgvector + tsvector

性能

速度快。 MCP 往返平均耗时 8.7 ms。在包含 700 篇文档的语料库上，混合搜索 p50 < 30 ms。关键词 QPS 从 100 篇文档时的 9,463 扩展至 10,000 篇文档时的 471（完整数据）。

找到正确答案。 在包含 558 篇真实开发文档、25 条手工编写的黄金查询上：Hit@5 = 0.92，nDCG@10 = 0.87，MRR = 0.79。在 BEIR SciFact（5,183 篇文档，公开检索基准）上：nDCG@10 = 0.671 — 与 Lucene BM25 基线的差距在 1% 以内。

节省令牌。 每次 search_docs 调用会返回 200–500 个令牌的相关片段，而完整文件读取原本需要 3,000–15,000 个令牌。使用 gnosis-mcp savings（v0.12.0+）跟踪自己的数据 — 每次调用都会将记录写入 search_access_log，并按工具和 --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×

根据语料库覆盖率和查询具体程度，压缩率通常为 10–60× — 请在自己的语料库上验证。access_log 默认开启；设置 GNOSIS_MCP_ACCESS_LOG=false 即可选择退出。

同一记录还可通过 gnosis-mcp usage（v0.17.4+）回答另一个问题 — 这个语料库会被问到什么，以及哪些问题找不到结果 — 包括调用次数、未匹配到任何内容的查询、最常提供服务的文档、从未提供服务的文档，以及哪些客户端在发起查询。

结果可复现。 gnosis-mcp eval 可在本地一秒内运行附带的检索质量评估工具 — 但它会将九篇硬编码的示例文档导入临时数据库，并回答十条附带查询，因此每个语料库都会得到相同的数字；它只是烟雾测试，并非对你自己的文档进行测量。要评估自己的语料库，请运行 python tests/bench/bench_real_corpus.py --corpus <docs-root> --golden <golden.jsonl>（上面的数据来自 tests/bench/golden-knowledge.jsonl）。tests/bench/*.py 可复现所有数据。方法说明：docs/benchmarks.md。

重排器默认关闭。 附带的 MS-MARCO 交叉编码器会使开发文档上的 nDCG@10 降低 27 个百分点，并使延迟增加 400×；BGE-reranker-v2-m3 会使其降低 31 个百分点，延迟增加 2400×。启用前请先在自己的语料库上测试 — 完整说明：bench-experiments-2026-04-18。

快速开始

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

就这样。你的 AI Agent 现在可以搜索文档了。

连接客户端 — 查看 llms-install.md，其中提供了适用于 Claude Code、Claude Desktop、Cursor、Zed、opencode、Windsurf、VS Code、JetBrains、Cline 及其他 MCP 客户端的可直接复制粘贴的 JSON 片段。

重新整理了文档？ gnosis-mcp ingest ./docs --prune 会重新摄取文档，并删除源文件已不存在的数据库块。--wipe 会先重置整个索引。也可以运行 gnosis-mcp prune ./docs --dry-run，预览将要删除的内容。清理操作只会处理由此根目录负责的文档：除非指定 --include-crawled / --include-generated，否则不会处理已爬取的网址和生成的文档（git 历史记录）。

想要语义搜索？ 添加本地嵌入，无需 API 密钥：

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

连接编辑器前先进行测试：

gnosis-mcp check                                # FTS5 + schema + row counts; non-zero exit = stop
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

然后将其接入你实际使用的客户端——只需一条命令，无需编辑路径：

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

setup 会解析运行它的机器上的命令路径，而不是 README 中假定的路径；它安装的每个代码块都由标记界定，因此重新运行时会原位改写。对于不读取服务自身 MCP instructions 的客户端，它还会安装一条简短规则，让 Agent 知道为何优先使用 gnosis，而不是读取文件——挂载了服务却无人调用，是一种悄无声息的故障模式。doctor 可用于检查这一情况：它会读取访问日志，并告知客户端是否确实调用了服务。详情见： docs/cli.md。

gnosis-mcp check 是准入检查：只有在后端已启动且服务所需的架构存在时才会以 0 退出；如果缺少任何内容，则会指出缺失项并以 1 退出。关键词搜索需要 SQLite FTS5，它是编译进 Python 的 SQLite 中的功能，并非必然可用——check 会将其报告为 FTS5: ready。其他问题请见：docs/troubleshooting.md。

使用 Docker 运行（无需安装）

多架构镜像，约 140 MB，内置本地 ONNX 嵌入和 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

也可以使用已提交的 docker-compose.yaml：

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

镜像标签包括 :latest、:<version>、:<version-minor>、:main、:sha-<sha>。生产环境配置方案——systemd、反向代理、安全检查清单、升级——请见 docs/deployment.md。

无需安装即可试用（uvx）

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

## 文档

权威索引——每个主题都只需点击一次即可访问：docs/overview.md。

大多数读者需要的几篇文档：

安装与客户端设置 — 各编辑器可直接复制粘贴的配置、Windows 路径、写入模式、嵌入
命令行界面 — 所有子命令和标志
配置 — 所有 GNOSIS_MCP_* 环境变量
MCP 工具与资源 — Agent 可调用的内容，以及每个工具的返回结果
部署 — Docker、systemd、反向代理、安全检查清单
故障排除 — 首次运行失败及恢复方法
基准测试 — 可复现的检索和延迟数据

docs/ 中还有：REST API · 嵌入服务 · 搜索的测量方法 · 重排序器实验 · 发布。

工具

Gnosis MCP 通过 MCP 提供九种工具和三种资源。AI Agent 需要了解文档信息时，会自动调用这些工具：

工具	功能	模式
`search_docs`	按关键词或混合语义与关键词搜索	读取
`get_doc`	按路径获取完整文档	读取
`get_related`	查找链接或相关文档（支持多跳查询和关系类型筛选）	读取
`search_git_history`	搜索已索引的 git 提交历史	读取
`get_context`	按使用频率加权的上下文摘要	读取
`get_graph_stats`	知识图谱拓扑：孤立节点、枢纽节点、关系分布	读取
`upsert_doc`	创建或替换文档	写入
`delete_doc`	删除文档及其分块	写入
`update_metadata`	修改标题、类别和标签	写入

六种读取工具始终会公布。三种写入工具需要设置 GNOSIS_MCP_WRITABLE=true；若未设置，它们会从 tools/list 中完全撤回，因此只读客户端绝不会被提供无法调用的工具。

资源 URI	返回内容
`gnosis://docs`	所有文档——路径、标题、类别、分块数量
`gnosis://docs/{path}`	完整文档内容
`gnosis://categories`	各类别及其文档数量

配置嵌入后，search_docs 会使用 Reciprocal Rank Fusion 融合关键词和语义搜索结果，并返回一个 highlight 字段，其中通过 <mark> 标签标出匹配词——这样查询只需几百个 token，而不必读取整个文件。get_context 是会话启动工具：它会按文档实际被检索的频率对文档排序，除非设置 GNOSIS_MCP_ACCESS_LOG=false 关闭追踪。

完整参考——包括每个参数、返回格式、错误以及图谱关系类型（related、content_link、git_co_change、git_ref，以及带类型的 frontmatter 边）：docs/tools.md。

配置

SQLite 无需任何配置，零配置即可使用。可通过 GNOSIS_MCP_* 环境变量进行覆盖。最常用的四项：

变量	默认值	说明
`GNOSIS_MCP_DATABASE_URL`	SQLite 自动	PostgreSQL URL（后端自动检测）或 SQLite 文件路径
`GNOSIS_MCP_WRITABLE`	`false`	启用 `upsert_doc` / `delete_doc` / `update_metadata`
`GNOSIS_MCP_EMBED_PROVIDER`	未设置	`local` 可启用混合搜索（需要 `[embeddings]` extra）；也可设为 `openai` / `ollama` / `custom`
`GNOSIS_MCP_API_KEY`	未设置	为除 `/health` 外的所有 REST 端点启用可选 Bearer 身份验证

其余 45 项配置——分块、搜索限制、RRF、重排、爬取、Webhook、列覆盖、日志记录——详见 docs/config.md。

后端会自动选择：将 GNOSIS_MCP_DATABASE_URL 设为 postgresql:// URL，即使用 PostgreSQL；不设置则使用位于 ~/.local/share/gnosis-mcp/docs.db 的 SQLite。可通过 GNOSIS_MCP_BACKEND=sqlite|postgres 覆盖。PostgreSQL 设置步骤——gnosis-mcp[postgres]、gnosis-mcp init-db、CREATE EXTENSION IF NOT EXISTS vector，然后运行 gnosis-mcp embed——详见 docs/overview.md。

嵌入

语义搜索是大多数配置都会需要的可选扩展。推荐使用本地 ONNX：零配置、无需 API 密钥，首次运行时会自动下载约 23 MB 的量化模型（MongoDB/mdbr-leaf-ir，Apache 2.0）。

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

远程提供方的使用方式相同，可运行 gnosis-mcp embed --provider openai（需要 GNOSIS_MCP_EMBED_API_KEY）或使用 --provider ollama。模型选项、维度、兼容 OpenAI 的 POST /v1/embed 服务，以及用于自有流水线的预计算向量，详见：docs/embeddings-service.md · docs/config.md。

可用平台

MCP Registry（供 VS Code MCP 库和 GitHub Copilot 使用） · PyPI · mcp.so · Glama · cursor.directory

面向 AI 的文档

文件	用途
`llms.txt`	快速概览——功能、工具和配置
`llms-full.txt`	单文件完整参考
`llms-install.md`	分步安装指南

开发

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                    # 862 tests, no database needed
ruff check src/ tests/

所有测试均可在不连接数据库的情况下运行。请保持这一点。

适合入门的贡献：新增嵌入提供方、导出格式，以及通过可选 extras 支持新文件类型的导入。较大的改动请先提交 Issue。

赞助

如果 Gnosis MCP 为你节省了时间，欢迎考虑赞助该项目。

许可证

MIT

了解更多

文档索引 — 所有文档页面的权威索引
安装指南 — 为每个 MCP 客户端提供可直接复制粘贴的设置步骤
已发布的文档 — 同一套文档，提供浏览版
PyPI — 发行版本、版本历史和安装说明
项目缘起 — 关于 gnosis-mcp 的文章

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。