Scholar RAG MCP

scholar-rag-mcp

ステータス：プレビューリリース（v0.4.0）。 インターフェースやストレージのレイアウトは、今後のバージョンで変更される可能性があります。

scholar-rag-mcp は、公開可能な学術論文ナレッジベース用の MCP ツールです。PDF のフォルダーを指定すると、実際の解析パイプライン（MinerU）を通じて各論文を取り込み、メタデータを正規化し、セクション構造に注釈を付け、テキストを分割して埋め込みを生成し、すべてを Qdrant に保存します。その後、エージェント（またはユーザー）は、11 個の MCP ツールを stdio 経由で使い、チャンクのセマンティック検索、PubMed 形式の文書クエリ、セクション単位での全文の読み取り、個別論文の追加・削除、ナレッジベースの管理を行えます。埋め込み、注釈付け、再ランキングには、OpenAI 互換のモデルサービス（vLLM など）を使用します。

機能

• 実際の取り込みパイプライン：MinerU による PDF 解析（python／cli／api バックエンド） -> メタデータ抽出（ローカルのヒューリスティック、CrossRef、オプションの GROBID） -> クリーンアップ -> セクション注釈付け -> 決定的なチャンク分割（300／1500／100 文字に設定可能） -> 埋め込み生成。
• 大規模環境でも高速な検索：埋め込みによる初回検索 + クロスエンコーダーによる再ランキング、オプションのメタデータフィルタリング（doc_id、section、year、journal、...）を Qdrant インデックス内で評価します。10 万チャンクでのクエリレイテンシは p95 で 1 秒未満です（docs/perf-report.md を参照）。
• 非同期ジョブ：create_kb／add_document はバックグラウンドジョブとして実行され、進捗は get_job から確認できます。安全に再起動でき、中断されたジョブは復旧され、再実行時にスキップされます。
• コンテキストに配慮した読み取り：サイズ上限付きのページ分割対応 get_document_text。まずアウトラインを確認し、必要に応じてページを取得します。
• stdio 経由の 11 個の MCP ツール：list_kbs、create_kb、delete_kb（二段階）、add_document、remove_document、get_document、get_document_text、list_documents、search_documents、search_chunks、get_job。
• 自己完結型のストレージ：ナレッジベースは単一のデータディレクトリに格納されます（既定の場所はプラットフォームによって異なります。「データのレイアウト」を参照）。Qdrant は自動起動（単一バイナリ、バージョン固定）するか、外部インスタンスに接続します。

インストール

scholar-rag-mcp は Linux x64、Windows x64、macOS（Intel および Apple Silicon）で動作します。 PyPI で公開されており、標準的な実行方法は uv を使うことです（適切な Python 3.12 が自動的に取得されます）。

uvx scholar-rag-mcp             # download and start the MCP server (stdio)

リポジトリをチェックアウトする必要はありません。モデルのエンドポイントとストレージは、 SCHOLAR_RAG_* 環境変数または <data_dir>/config.json で設定します（.env.example を参照）。 自動起動に使う Qdrant バイナリは、初回使用時にプラットフォームごとにダウンロードされます。

ワンクリックでのインストール／アンインストール

uvx scholar-rag-mcp install --with-mineru # install via uv, provision managed MinerU, register MCP clients
uvx scholar-rag-mcp install              # MCP only; bring your own parse service (see PDF parsing)
scholar-rag-mcp uninstall                # unregister clients and remove the package

uvx scholar-rag-mcp install は uv tool install を通じてパッケージをインストールし、6 つのモデルエンドポイント設定（chat／embed／rerank のベース URL とモデル名）を対話形式で設定します。SCHOLAR_RAG_* の値、または --chat-base-url／--chat-model／--embed-base-url／--embed-model／--rerank-base-url／--rerank-model のフラグが指定されていない場合は、「最小限の環境」に記載された既定値が使われます。--yes を指定すると、確認を求めずにすべての既定値を受け入れます。続いて、対応している 4 つの MCP クライアント（Claude Desktop、Claude Code、opencode、Codex）を検出し、ユーザーレベルの設定ファイルに scholar-rag-mcp エントリをマージしてツールを登録します。変更されるのはそのエントリのみです。単一のクライアントに登録するには --client <name> を指定します。解析できない設定ファイル（コメント付き JSON など）は変更せず、代わりに手動で追加するスニペットを表示します。

scholar-rag-mcp uninstall は、検出されたクライアントから scholar-rag-mcp エントリを削除し、uv tool uninstall を実行します。ナレッジベースのデータディレクトリは保持されます。--purge を指定すると、明示的な確認の後にデータディレクトリも削除します（--yes を指定すると確認を省略します）。

ソースから実行（開発）

pixi が必要です。リポジトリのルートから実行します。

pixi install                      # installs the default environment

pixi 環境は、サポートされている4つのターゲットすべてでロックされています。このプロジェクトでは、用途の異なる2つの pixi 環境を定義しています。

環境	用途
default	コアランタイムと開発ツール（pytest/ruff/mypy）です。MCP サーバーとすべてのスクリプトはここで実行します。
mineru	MinerU（==3.4.5）と、そのランタイムスタック一式（固定バージョンの transformers<5、torch、onnxruntime、shapely など）が追加されます。PDF の解析と e2e スモークテストに使用します。

組み込みの doctor で環境を確認します。

pixi run python scripts/doctor.py

モデルのデプロイ

環境（「chat」「embed」「rerank」クライアント）は、OpenAI 互換の HTTP エンドポイントを想定しています。 scripts/serve_models.sh は、リファレンスモデルセット用の vLLM インスタンスを3つ起動します。

サービス	モデル	ポート
chat	Qwen3.5-0.8B	8101
embed	jina-embeddings-v5-text-small	8102
rerank	jina-reranker-v3.5	8103

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL、SCHOLAR_RAG_EMBED_MODEL、SCHOLAR_RAG_RERANK_MODEL は必須です。いずれかが未設定の場合、スクリプトは未設定の変数を列挙するメッセージを表示して終了します。それぞれの値には、ローカルの HuggingFace モデルディレクトリへの絶対パスを指定する必要があります。vLLM は各モデルをディレクトリのベース名と同じ短い名前で提供するため、クライアント設定にはその短い名前を指定してください（提供時の名前はフルパスとは一致しなくなります）。.env.example 内の /path/to/... プレースホルダーを適宜置き換えてください。ポート（CHAT_PORT/EMBED_PORT/RERANK_PORT）と GPU ID は省略可能で、動作するデフォルト値が設定されています。

このスクリプトは、デフォルトのモデルセットで検証済みの vLLM フラグを渡します。特に --trust-remote-code は、固定バージョンの vLLM（0.27.1）で3つすべてのモデルに必要です。モデルの読み込みには数分かかります。スクリプトは、3つすべてが応答するまでヘルスチェックをポーリングします。

scripts/serve_models.sh はLinux 専用です（bash + CUDA + vLLM。vLLM は Windows をサポートしていません）。Windows/macOS では、代わりに *_BASE_URL 設定を任意の OpenAI 互換サーバーに向けてください。たとえば、Ollama（http://127.0.0.1:11434/v1）、LM Studio のローカルサーバー、または llama.cpp サーバーを使用できます。また、各 *_MODEL には、そのサーバーが返すモデル名を設定してください。rerank エンドポイントは /v1/rerank を公開している必要があります（または、rerank を embed のみのフォールバックに任せてください）。

最小限の環境設定

.env.example をベースに、少なくともモデルエンドポイントを設定します（serve スクリプトが公開する短い名前、つまり各モデルディレクトリのベース名を使用します）。

# data dir is optional - defaults to the platform data directory (see Data layout)
# SCHOLAR_RAG_DATA_DIR=
# SCHOLAR_RAG_QDRANT_STORAGE_DIR=

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

embed モデルの次元は kb 作成時に kb_meta.json に記録されるため、後から embedding モデルを変更する場合は新しい kb が必要です。

PDF の解析（MinerU）

v0.4.0 以降、デフォルトの解析バックエンドは api です。推奨される設定はマネージドサイドカーです。MinerU を分離された Python 3.12 venv にインストールし（MinerU には Python >=3.10,<3.14 が必要です）、初回の解析時に mineru-api を自動起動します。

scholar-rag-mcp install --with-mineru

初回の解析時に MinerU のモデルがダウンロードされます。中国からアクセスしやすいミラーが必要な場合は、MINERU_MODEL_SOURCE=modelscope を設定してください。

セルフ管理の代替方法：任意の Python 3.12 環境に MinerU をインストールし、mineru-api --host 127.0.0.1 --port 8010 を実行して、デフォルト設定（SCHOLAR_RAG_MINERU_BACKEND=api、SCHOLAR_RAG_MINERU_API_URL=http://127.0.0.1:8010）を維持します。

python バックエンド（プロセス内インポート）と cli バックエンド（ファイルごとにサブプロセスを実行）も、SCHOLAR_RAG_MINERU_BACKEND から引き続き利用できます。

MCP クライアントの設定

MCP クライアントを uvx エントリーポイントに向け、モデルエンドポイントを env ブロックで設定します（OpenAI 互換サーバーであれば利用できます。「モデルのデプロイ」を参照してください）。サーバーが起動することを確認するには、ターミナルで uvx scholar-rag-mcp を実行します。標準入出力で MCP クライアントからの接続を待機します（終了するには Ctrl+C を押します）。

Claude（Claude Desktop / claude CLI）

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "uvx",
      "args": ["scholar-rag-mcp"],
      "env": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["uvx", "scholar-rag-mcp"],
      "environment": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

ソースチェックアウトから実行する場合は、代わりに pixi run scholar-rag-mcp をコマンドとして使用し（リポジトリのルートから実行）、同じ変数をシェルで設定します。

ツール

ツール	用途
list_kbs	ドキュメント数／チャンク数とステータスを含むナレッジベースの一覧を表示します。
create_kb	フォルダー内のすべての PDF を新しい kb に非同期で取り込みます（job_id を返します）。
delete_kb	kb を2段階で削除します（下記参照）。
add_document	既存の kb に単一の PDF を非同期で取り込みます（job_id を返します）。
remove_document	1つのドキュメントを同期的に削除します（Qdrant のポイント、カタログ、ファイル）。
get_document	ドキュメントの概要：メタデータ、要約、セクションのアウトライン、合計サイズ。
get_document_text	1つのドキュメントまたは単一のセクションの全文をページネーションで読み取ります。
list_documents	kb 内のドキュメントをページネーションで閲覧します。
search_documents	PubMed 形式のドキュメント単位の検索（FTS + タイトル／著者／ジャーナル／年）。
search_chunks	メタデータフィルターと埋め込み＋再ランキングのスコアを使ったセマンティックなチャンク検索。
get_job	バックグラウンドジョブのステータス／進捗／結果／経過時間を照会します。

データの配置

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default: platform data dir (below)
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
├── bin/                        # auto-downloaded Qdrant binary (v1.12.5)
└── qdrant-storage/             # default QDRANT_STORAGE_DIR location

プラットフォームごとのデフォルトの data_dir（SCHOLAR_RAG_DATA_DIR で上書きできます）：

プラットフォーム	デフォルト
Linux	$XDG_DATA_HOME/scholar-rag（設定されていない場合は ~/.local/share/scholar-rag）
macOS	~/Library/Application Support/scholar-rag
Windows	%LOCALAPPDATA%\scholar-rag

Qdrant のストレージのデフォルトは <data_dir>/qdrant-storage です（SCHOLAR_RAG_QDRANT_STORAGE_DIR で上書きできます）。9p／ネットワークマウントではなく、ローカルファイルシステム上に配置する必要があります。

Linux で v0.1.0 からアップグレードする場合：以前のデフォルト（~/.scholar-rag および ~/.local/share/scholar-rag/qdrant）は初回起動時に自動的に移行されます。新しい場所にすでにデータがある場合は、警告を表示して移行をスキップし、古いファイルはそのまま残します。

kb の2段階削除

delete_kb は、誤った引数での初回呼び出しによって削除が実行されることはありません。

1. delete_kb(kb="...") を呼び出します。kb の統計情報と、10分間有効な confirm_token が返されます。
2. delete_kb(kb="...", confirm_token="<token>") を呼び出すと、Qdrant コレクション、kb ディレクトリ、およびジョブ履歴が実際に削除されます。

開発

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

リリースノート

既知の制限事項とアップグレード方法については、 docs/handoffs/release-notes-v0.4.0.md、 docs/handoffs/release-notes-v0.3.0.md および docs/handoffs/release-notes-v0.2.1.md を参照してください。

特に留意すべき既知の制約：

• Qdrant は v1.12.5 に固定されています。glibc 2.35 で動作する最高バージョンであり、初回使用時に自動起動でダウンロードされます。glibc >= 2.38 では、より新しいバージョンを実行できますが、このリリースではデータ形式に下位互換性がないため、古い kb との互換性はありません。
• MinerU は専用の pixi 環境で実行されます。transformers のバージョンが vLLM のものと相互に排他的であるためです。そのため、PDF の解析には pixi run -e mineru が優先されます。
• MinerU の重み（約 3.2 GB）は、初回の解析時に ~/.cache/modelscope/ へダウンロードされます。
• メタデータのタイトル判定ヒューリスティック：MinerU の Markdown が #／## 見出しで始まる場合に限り、タイトルはローカルで抽出されます。そのため、先頭の ## Abstract などがタイトルと誤認されることがあります。これはローカルヒューリスティックのメタデータ階層にのみ影響します。DOI が見つかった場合に使われる CrossRef 階層では、通常この問題が修正されます。
• ツールのディスパッチ：ツールに渡された未知の追加引数は、拒否されずに黙って無視されます。
• 9p ストレージの制限：Qdrant のストレージはローカルファイルシステム上に配置する必要があります。
• プラットフォームのサポート：Linux x64／Windows x64／macOS Intel＋Apple Silicon。vLLM のデプロイスクリプトは Linux 専用です。Windows／macOS では、任意の OpenAI 互換サーバーを使用してください。
• Windows の長いパス：深い階層のデータディレクトリでは、260文字の上限に達する可能性があります。SCHOLAR_RAG_DATA_DIR は浅い階層にするか、Windows の長いパスのサポートを有効にしてください。
• macOS x64 CI：コードレベルでのみカバーされています。GitHub の x64 macOS ランナーには larger-runner の課金が必要なため、CI マトリックスでは macOS arm64（macos-latest）を実行します。