Gnosis Mcp

ドキュメントサーバーがない場合

• LLMが存在しないAPIシグネチャを幻覚します
• ファイル全体をコンテキストに投入 — ドキュメント1件あたり3,000～15,000トークン
• アーキテクチャ上の決定が、数十ものファイルに埋もれています
• 検索のたびに、コンテキストのコストが全額かかります

Gnosis MCPを使う場合

• search_docsは、ランキング付きでハイライトされた抜粋を返します — 通常300～800トークンです
• 学習データからの推測ではなく、実際のドキュメントに基づいた確かな回答が得られます
• 数百のファイルをひとつのローカルインデックスにまとめ、複数ドキュメントを瞬時に検索できます
• コーパスが質問を網羅している場合、検索ごとのトークン数を5～10分の1に削減できます

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 融合を調整できます。
• クロスエンコーダーによる再ランキング — 2,200 万パラメーターの ONNX モデルを含む、オプションの [reranking] エクストラです。デフォルトでは無効です。有効にする前に、ご自身のコーパスでテストしてください — 当方の測定では、同梱の MS-MARCO 再ランカーは開発ドキュメントの検索性能を低下させます。
• Git 履歴 — コミットメッセージを検索可能なコンテキストとして取り込みます（ingest-git）
• ウェブクローリング — サイトマップまたはリンクのクロールを使って、あらゆるウェブサイトからドキュメントを取り込みます
• マルチフォーマット — .md .txt .ipynb .toml .csv .json と、オプションの .rst .pdf に対応します
• 自動リンク — relates_to フロントマターによって、ナビゲーション可能なドキュメントグラフを作成します
• 監視モード — ファイルの変更時に自動で再取り込みします
• 古いドキュメントの整理 — gnosis-mcp ingest --prune は、ソースファイルが削除されたチャンクを削除します。再取り込み前に完全にリセットするには --wipe を使用します。
• 組み込みの評価ハーネス — gnosis-mcp eval を実行すると、同梱の固定フィクスチャセットを対象に、Hit@K／MRR／Precision@K を1つのコマンドで出力します
• 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 を呼び出すと、ファイル全体を読み込む場合に必要な3,000〜15,000トークンの代わりに、的を絞ったスニペットを200〜500トークンで返します。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 を設定します。

同じ台帳を使って、もう1つの疑問、つまりこのコーパスには何が尋ねられていて、どこで答えが見つからないのかも、gnosis-mcp usage（v0.17.4+）で確認できます。呼び出し回数、何も一致しなかったクエリ、最も多く提供されているドキュメント、一度も提供されていないドキュメント、検索に利用しているクライアントがわかります。

再現可能です。 gnosis-mcp eval は、検索品質の評価ハーネスをローカルで1秒以内に実行します。ただし、一時データベースにハードコードされたサンプルドキュメント9件を取り込み、同梱のクエリ10件に回答するため、どのコーパスでも同じ数値が返されます。これはスモークテストであり、ご自身のドキュメントを測定するものではありません。ご自身のコーパスを評価するには、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 は nDCG@10 を31ポイント低下させ、レイテンシを2,400倍に増加させます。有効にする前に、ご自身のコーパスでテストしてください。詳しい結果は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 エージェントがドキュメントを検索できるようになりました。

クライアントを接続する — Claude Code、Claude Desktop、Cursor、Zed、opencode、Windsurf、VS Code、JetBrains、Cline、その他すべての MCP クライアント向けのコピー＆ペースト可能な JSON スニペットについては、llms-install.md をご覧ください。

ドキュメントを再編成しましたか？ gnosis-mcp ingest ./docs --prune を実行すると、再取り込みを行い、ソースファイルが存在しなくなった DB チャンクを削除します。--wipe を指定すると、最初にインデックス全体をリセットします。または、gnosis-mcp prune ./docs --dry-run を実行すると、削除される項目を事前に確認できます。プルーニングの対象は、このルートが管理するドキュメントのみです。--include-crawled / --include-generated で指定しない限り、クロールした URL と生成されたドキュメント（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

次に、実際に使うクライアントに組み込みます。コマンドは 1 つで、パスの編集は不要です。

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 を読み取らないクライアントには、ファイルを読むより gnosis を優先する理由をエージェントに与える短いルールもインストールします。マウントされたサーバーが呼び出されないのは、気づきにくい障害の原因です。これを確認するには doctor を使います。アクセスログを読み取り、クライアントが実際にサーバーを呼び出したかどうかを通知します。詳細については、docs/cli.md をご覧ください。

gnosis-mcp check は判定ゲートです。バックエンドが起動し、サーバーが必要とするスキーマが存在する場合にのみ 0 で終了します。不足している項目があれば、それを示してから 1 で終了します。キーワード検索には SQLite FTS5 が必要です。これは Python の SQLite に組み込まれている機能ですが、必ず使えるとは限りません。check は利用可能な場合に FTS5: ready と表示します。それ以外の問題については、docs/troubleshooting.md をご覧ください。

# 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 up -d
docker compose exec gnosis gnosis-mcp ingest /docs --embed

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

正規の目次 — すべてのトピックにワンクリックでアクセスできます：docs/overview.md。

ほとんどの読者に必要な主な項目：

• インストールとクライアントのセットアップ — 各エディター用のコピー＆ペースト可能な設定、Windows のパス、書き込みモード、埋め込み
• CLI — すべてのサブコマンドとフラグ
• 設定 — すべての GNOSIS_MCP_* 環境変数
• MCP ツールとリソース — エージェントが呼び出せる機能と、それぞれが返す内容
• デプロイ — Docker、systemd、リバースプロキシ、セキュリティチェックリスト
• トラブルシューティング — 初回実行時の問題と復旧方法
• ベンチマーク — 再現可能な検索精度とレイテンシの数値

docs/ にあるその他のドキュメント：REST API · 埋め込みサービス · 検索の測定方法 · リランカーの実験 · リリース。

ツール

Gnosis MCP は、MCP を通じて 9 つのツールと 3 つのリソースを公開します。ドキュメントの情報が必要になると、AI エージェントがこれらを自動的に呼び出します。

6 つの読み取りツールは常に公開されます。3 つの書き込みツールを使用するには GNOSIS_MCP_WRITABLE=true が必要です。設定されていない場合、これらのツールは tools/list から完全に除外されるため、読み取り専用クライアントに呼び出せないツールが渡されることはありません。

埋め込みが設定されている場合、search_docs はキーワード検索とセマンティック検索の結果を Reciprocal Rank Fusion で統合し、一致した語句を <mark> タグで示す highlight フィールドを返します。これにより、ファイル全体ではなく数百トークンで検索結果を確認できます。get_context はセッション開始時に使用するツールです。GNOSIS_MCP_ACCESS_LOG=false でトラッキングを無効にしない限り、ドキュメントが実際に取得された回数に基づいて順位付けします。

完全なリファレンス — すべてのパラメーター、戻り値の形式、エラー、グラフの関係タイプ（related、content_link、git_co_change、git_ref、および型付きの frontmatter エッジ）：docs/tools.md。

設定

SQLite では設定は不要です。設定なしで動作します。GNOSIS_MCP_* 環境変数で上書きできます。特によく使われる 4 つは次のとおりです。

残りの 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 向けドキュメント

開発

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/

すべてのテストはデータベースなしで実行できます。この状態を維持してください。

初めての貢献に適した内容：新しい埋め込みプロバイダー、エクスポート形式、新しいファイル形式の取り込み（オプションのエクストラ経由）。大きな変更の場合は、まず Issue を作成してください。

スポンサー

Gnosis MCP によって時間を節約できた場合は、プロジェクトへのスポンサー提供をご検討ください。

ライセンス

MIT

詳細情報

• ドキュメントの目次 — すべてのドキュメントページをまとめた公式の案内です
• インストールガイド — すべてのMCPクライアント向けのコピー＆ペーストで使えるセットアップ手順です
• 公開ドキュメント — 同じドキュメントを閲覧しやすい形式で掲載しています
• PyPI — リリース、バージョン履歴、インストール情報です
• 開発の背景 — gnosis-mcpの背景についての記事です