Scholar MCP

Scholar MCP

学術論文、特許、書籍、規格、PDF 変換

ドキュメント | 設定ウィザード | PyPI | Docker

機能

学術情報のソース種別ごとに整理された29個のツールを提供します。

ソースドメイン

• 論文：年、掲載先、分野、引用数で絞り込める全文検索；DOI、S2 ID、arXiv ID、ACM ID、または PubMed ID による個別論文の検索；著者プロフィールと名前の検索；被引用文献、引用文献、BFS によるグラフ探索、最短経路による橋渡しの発見；肯定例・否定例に基づくおすすめ；OpenAlex による掲載先情報の補完を含む、BibTeX／CSL-JSON／RIS 形式での引用情報生成。
• 特許：EPO OPS を介した 100 以上の特許庁を対象とする検索。CPC、出願人、発明者、管轄区域による絞り込み；書誌情報、請求項、説明、ファミリー、法的情報、引用の各セクション；Semantic Scholar を介した非特許文献から論文への紐付け、および論文から特許への引用の発見。EPO の認証情報は任意です。他のドメインは認証情報なしで利用できます。
• 書籍：API キー不要の Open Library によるタイトル／著者／キーワード検索；ISBN-10／13、または Open Library の作品／版 ID による検索；人気順の分野別おすすめ；Google Books の抜粋とプレビューリンク；図書館検索用の WorldCat パーマリンク；表紙画像のキャッシュ。externalIds に ISBN が含まれる論文は、Open Library から出版社、版、表紙 URL、分野のデータが自動的に補完されます。
• 規格：NIST、IETF、W3C、ETSI 規格の識別子解決、検索、メタデータ取得。docling による全文取得と Markdown 変換も任意で利用できます。ISO、IEC、IEEE、Common Criteria（CC）、CEN/CENELEC の Tier 2 メタデータ（ISO／IEC／IEEE の合同規格、および CC ↔ ISO/IEC 15408 の相互リンクを含む）は、sync-standards を介してローカルに同期されます。ISO、IEC、IEEE では、未同期の識別子に対するライブ取得のフォールバックを利用できます。CC と CEN にはライブ API がないため、事前の同期が必要です。規格のパターン（RFC、ISO、NIST SP、IEEE、EN、CC）に一致する引用は、利用可能な場合、識別子、タイトル、本文、ステータス、全文 URL を含む構造化された standard_metadata で自動的に補完されます（docs/guides/standards.md を参照）。

ドメイン横断機能

• 情報補完パイプライン：複数のソースを使った段階的な情報補完。OpenAlex（OA ステータス、所属機関、資金提供者、概念）、CrossRef（出版社、ページ範囲、掲載誌名）、Google Books（プレビューリンク、抜粋）、Open Library（書籍メタデータ）から情報を取得します。論文と書籍の検索結果に対して自動的に実行されます。
• PDF 変換：docling-serve を介してオープンアクセス PDF をダウンロードし、Markdown に変換します。数式や図に対する VLM による情報補完も任意で利用できます。Semantic Scholar に OA リンクがない場合は、ArXiv、PubMed Central、Unpaywall に自動的にフォールバックします。他の場所で見つかった PDF は URL から直接ダウンロードできます。変換されたテキストはページ分割されるため、大きなドキュメントも MCP のレスポンスに収まります。
• インテリジェントキャッシュ：テーブルごとに TTL（論文／著者は 30 日、引用／参考文献は 7 日）を設定し、識別子のエイリアスに対応した SQLite ベースのキャッシュです。
• 認証：ベアラートークン、OIDC（OAuth 2.1）、または両方の同時利用（マルチ認証）。
• マルチトランスポート：stdio（Claude Desktop）、HTTP（streamable-http）、SSE トランスポート。
• Linux パッケージ：systemd サービスとセキュリティ強化機能を備えた .deb および .rpm パッケージ。

ドメイン別の対応範囲

ドメインごとに対応範囲の深さは異なります。論文は現在、最も豊富なツール群を備えています（引用グラフ、おすすめ、他の 3 つのドメインすべてとの相互参照）。規格は最も限定的です。これは公開データの入手しやすさを反映したものであり、価値の序列を示すものではありません。論文の執筆では通常、引用や先行技術の調査に 4 種類すべてのソースが必要になります。対応範囲の拡充作業は GitHub issues と milestones で管理されています。ロードマップは今後の方針を示すものであり、完全性を約束するものではありません。

できること

このサーバーを MCP クライアント（Claude など）にマウントすると、次のことができます。

• 分野を調査する：「2020 年から 2024 年までのグラフニューラルネットワークに関する被引用数上位 20 件の論文を探し、文献レビューのアウトラインを作成してください。」search_papers + get_citations + enrich_paper を組み合わせます。
• 引用経路をたどる：「『Attention is All You Need』から『RLHF for dialogue agents』までの最短の引用経路は何ですか？」find_bridge_papers + get_citation_graph を使用します。
• 先行技術を相互参照する：「この特許ファミリーについて、引用されている学術論文と、説明文に登場する書籍や規格を一覧表示してください。」get_patent + batch_resolve + 規格／書籍のエンリッチメントを組み合わせます。
• 参考文献リストを生成する：「これら 30 件の DOI について、OpenAlex の会議情報を含めた BibTeX を出力してください。」generate_citations を使用します。
• 規格を調べる：「RFC 9000 の最新状況を教えてください。また、Markdown の全文を取得してください。」resolve_standard_identifier + get_standard を使用します。

インストール

PyPI から

pip install pvliesdonk-scholar-mcp

pyproject.toml の PROJECT-EXTRAS-START / PROJECT-EXTRAS-END センチネルを使ってオプションの追加機能を加える場合は、以下に記載してください。

• [all]：すべての本番機能を 1 つの追加機能にまとめます。Linux パッケージと Claude Desktop バンドルでインストールされます。
• [debug]：リモートデバッガー（debugpy）を追加します。リモートデバッグを参照してください。

ベースパッケージには fastmcp-pvl-core 経由で FastMCP がすでに含まれているため、pip install pvliesdonk-scholar-mcp だけで scholar-mcp serve を実行できます。従来の [mcp] 追加機能は、既存のインストールコマンドが引き続き動作するように残されています。ベースパッケージに含まれるもの以外は追加されません。

ソースから

git clone https://github.com/pvliesdonk/scholar-mcp.git
cd scholar-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/scholar-mcp:latest

最新リリースではなく、マージされた最新のコードを実行するには、ローリング edge タグを使用してください。main へのマージごとに再ビルドされ、バージョン識別情報は付与されません。タグの一覧については、イメージタグを参照してください。

docker pull ghcr.io/pvliesdonk/scholar-mcp:edge

リポジトリのルートには compose.yml が用意されており、そのまま実行できます。.env.example を .env にコピーしてから、docker compose up -d を実行してください。ホスト上のポート 8000 を公開し、リバースプロキシがないことを前提としています。設定の分割、ドメイン用センチネルブロック、Traefik オーバーレイについては、Docker Composeで説明しています。

リモートの Python デバッガーを接続する方法（開発専用。プロトコルは認証されません）については、リモートデバッグを参照してください。

Linux パッケージ（.deb / .rpm）

GitHub Releasesページから .deb または .rpm パッケージをダウンロードしてください。どちらもセキュリティ強化済みの systemd ユニットをインストールします。環境設定は /etc/scholar-mcp/env から読み込まれます（同梱の /etc/scholar-mcp/env.example をコピーしてください）。

Claude Desktop（.mcpb バンドル）

GitHub Releasesページから .mcpb バンドルをダウンロードし、ダブルクリックしてインストールするか、次を実行してください。

mcpb install scholar-mcp-<version>.mcpb

Claude Desktop では GUI ウィザードで必要な環境変数の入力が求められるため、JSON を手動で編集する必要はありません。

Claude Desktop の手動設定とセットアップのオプションについては、Claude Desktop のデプロイを参照してください。

リリースチャネル

成果物は3つのチャネルで公開されます。各行には、そのチャネルで公開されるものをすべて記載しています。

チャネル	バージョンの識別情報	成果物
edge（ローリング）	なし。コミットが識別情報です	main へのマージごとに再ビルドされる Docker イメージ :edge、ワークフロー成果物 mcpb-bundle-edge としての .mcpb バンドル、成果物 plugin-zip-edge としての Claude Code プラグイン .zip、ローリングする unstable ドキュメントバージョン。Git タグ、GitHub リリース、PyPI エントリーは残りません。
プレリリース	リリースプルリクエストで算出・レビューされる vX.Y.Z-rc.N	PyPI（プレリリース X.Y.ZrcN として）、wheel、sdist、.deb／.rpm パッケージ、.mcpb バンドル、プラグイン .zip、SBOM を添付した GitHub リリース、不変の vX.Y.Z-rc.N タグと順序を考慮したローリング rc タグが付いた Docker イメージ。プラグインマーケットプレイス、MCP レジストリ、ドキュメントのデプロイはスキップされます。
安定版	vX.Y.Z	すべて：PyPI、Docker（バージョンタグと、順序を考慮した latest／vX／vX.Y）、.deb／.rpm、GitHub リリースアセット（wheel、sdist、.mcpb バンドル、プラグイン .zip、SBOM）、プラグインマーケットプレイスと MCP レジストリのエントリー（そのリリースが最新の安定版の場合）、順序を考慮した latest エイリアス付きのバージョン別ドキュメント。

候補版の .mcpb バンドルをインストールできるよう、プレリリースも PyPI に公開されます。このバンドルはコードを内包せず、PyPI を参照します。通常のインストーラーには表示されません。PEP 440 のリゾルバーは、要件でプレリリースを指定するか、--pre を渡さない限り、プレリリースをスキップするためです。pip install pvliesdonk-scholar-mcp==X.Y.ZrcN で候補版を名前で指定できます。PyPI では PEP 440 の正規形式で表記されますが、タグでは SemVer が使われます。ローリングポインターは順序を考慮するため、古い release/X.Y ブランチから切り出したパッチリリースによって latest 系のタグが古いコンテンツに戻ることはなく、すでにリリース済みのバージョンの候補版によって rc が移動することもありません。全体像については、リリースプロセスを参照してください。

クイックスタート

scholar-mcp serve                                # stdio transport
scholar-mcp serve --transport http --port 8000   # streamable HTTP

MCP トランスポートを使わずにドメインロジックを組み込むライブラリ利用では、scholar_mcp パッケージから直接インポートしてください。エントリーポイントについては、プロジェクトの src/scholar_mcp/ 以下にあるドメインモジュールを参照してください。

サーバー情報

サーバーには組み込みの get_server_info ツールが登録されており（fastmcp_pvl_core.register_server_info_tool 経由）、オペレーターは1回の MCP 呼び出しでデプロイ済みバージョンを確認できます。デフォルトのレスポンスには server_name、server_version、core_version が含まれます。リモートのアップストリームと通信するサーバーでは、src/scholar_mcp/server.py の DOMAIN-UPSTREAM-START／DOMAIN-UPSTREAM-END センチネル内でアップストリームのバージョン情報を報告するよう設定します。設定方法については、tool-registrationを参照してください。

ヘルスチェック

サーバーは、MCP マウントの外部かつ認証の対象外で、fastmcp_pvl_core.register_health_routes を介して /health（稼働状態。静的な 200）と /health/ready（準備状態。バックエンドストアまたはドメインチェックに失敗した場合は 503）を提供します。compose.yml は前者をプローブします。ドメインの準備状態チェックは、src/scholar_mcp/server.py の health_checks 辞書に追加します。ルート、マウントパスのルール、SCHOLAR_MCP_HEALTH_DETAIL については、Docker デプロイを参照してください。

設定

fastmcp-pvl-core をベースにしたすべてのサービスで共通する、最もよく使われる環境変数です。

変数	デフォルト値	説明
SCHOLAR_MCP_KV_STORE_URL	file:///data/state	状態を必要とする、すべての pvl-core サブシステムで共有する永続状態バックエンドの URL です。memory:// はプロセス内でのみ有効で、再起動すると失われます。file:///path は 1 台のサーバー上に永続化します。redis://、dynamodb://、mongodb:// には、それぞれ対応する追加パッケージが必要です。未設定の場合、Docker イメージがマウントするボリュームのパス file:///data/state がデフォルトになります。このディレクトリを使用できないホストでは、警告を出して memory:// がデフォルトになります。
SCHOLAR_MCP_LOG_LEVEL	INFO	FastMCP を含む、プロセス内のすべてのロガーのログレベルです（DEBUG / INFO / WARNING / ERROR / CRITICAL）。-v CLI フラグを指定すると DEBUG に上書きされます。接頭辞のない FASTMCP_LOG_LEVEL も、1 つのメジャーバージョンの間は引き続き使用でき、非推奨を知らせる警告が記録されます。
SCHOLAR_MCP_LOG_FORMAT	（なし）	ログの出力形式です。rich はターミナル向けの、レコードごとに 1 行の色付き event key=value 形式です。json はログ収集ツール向けの、レコードごとに 1 つの JSON オブジェクトです。未設定の場合、stderr がターミナルなら rich、それ以外なら json が選択されるため、コンテナや journald では設定なしで JSON が出力されます。

この表とドメイン設定の表は、厳選した項目のみを掲載しています。サーバーが読み取るすべての変数を含む完全な自動生成リファレンスは、設定リファレンスをご覧ください。.env.example には同じ項目がコピーして貼り付けられる形式で記載されています。

認証

呼び出し元は、ベアラートークンまたは OIDC（併用不可）で認証します。設定方法、複数のサブジェクトに対応するトークン、OIDC、トラブルシューティングについては、認証ガイドをご覧ください。

スキャフォールド生成後のチェックリスト

copier copy と gh repo create --push の実行後：

1. README と AGENTS.md にある DOMAIN ブロック（DOMAIN センチネルコメントが付いたすべてのセクション）を記入します。GENERATED-ENV-TABLE-* の領域は DOMAIN ブロックではありません。設定ジェネレーターが管理し、実行のたびに書き換えます。
2. GitHub シークレットを設定します（以下を参照）。
3. 開発用ツールとドキュメント用ツールをインストールします：uv sync --all-extras --all-groups。
4. pre-commit フックをインストールします：uv run pre-commit install。
5. ゲートをローカルで実行します：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
6. 最初のコミットをプッシュします。CI は成功するはずです。

GitHub シークレット

CI ワークフローでは、必須のリポジトリシークレットを 2 つと、任意の Claude トークンを 1 つ参照します。Settings → Secrets and variables → Actions から、または gh secret set を使って設定してください。

シークレット	使用先	生成方法
RELEASE_TOKEN	release-prepare.yml、release.yml、copier-update.yml、renovate.yml、bootstrap.yml	https://github.com/settings/personal-access-tokens/new で、contents: write、pull_requests: write、administration: write を付与したきめ細かな PAT を作成します（bootstrap はリポジトリのルールセット、自動マージ、セキュリティ設定、About ブロックを適用します）。リポジトリ管理者のアカウントに属している必要があります。付属のルールセットでは管理者ロールにバイパス権限を付与しており、リリースプルリクエストのマージ後に knope が作成するリリースタグと GitHub リリースでも、この権限が必要です（トークンが作成するプルリクエストでも CI を実行するために必要です）。このリポジトリのみにスコープを限定してください。
SONAR_TOKEN	ci.yml	https://sonarcloud.io：リポジトリをインポートした後、その Administration → Analysis Method ページを開きます。SonarQube Cloud は Automatic Analysis が有効な状態では CI スキャンを拒否するため、まずここで Automatic Analysis をオフにしてください。GitHub Actions を選択すると、トークンが表示されます。このシークレットが設定されるまで、CI はスキャンをスキップします。
CLAUDE_CODE_OAUTH_TOKEN	claude.yml	任意です。ローカルで claude setup-token を実行し、@claude またはオプトインした自動レビューを使う場合にのみ設定してください。

gh secret set RELEASE_TOKEN
gh secret set SONAR_TOKEN
# Optional: enables @claude and opted-in automatic review.
gh secret set CLAUDE_CODE_OAUTH_TOKEN

依存関係の更新は Renovate（renovate.yml）が処理し、 RELEASE_TOKEN を再利用します。uv.lock を維持し、CI Success チェックが 成功するとパッチ／マイナーの更新を自動マージします。bootstrap.yml は 自動マージを有効にし、リポジトリのルールセット（.github/rulesets/）を適用し、 非公開の脆弱性レポートと Dependabot アラートを有効にして、初回の push 時に pyproject.toml からリポジトリの About ブロック（説明、Web サイト、 トピック）を設定します。ブランチごとの保護設定、バイパスモデル、 セキュリティ設定については、 リポジトリの保護を参照してください。GitHub Actions は copier テンプレートで更新され、リポジトリごとではなく copier update で反映されます。

GITHUB_TOKEN は自動的に提供されるため、操作は不要です。

ローカル開発

PR ゲート（CI と同じです）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

Pre-commit は各コミットでゲートの一部を実行します。詳細は .pre-commit-config.yaml を、Hard PR Acceptance Gates の全体については AGENTS.md を参照してください。

CI では、Python 3.11 から 3.14 までの各バージョンでテストが成功する必要があります。Python 3.14 ではブランチカバレッジも収集し、全体およびパッチのカバレッジしきい値 80% を適用します。 このテストコマンドを再現するには、 uv run --python 3.14 pytest --cov --cov-report=xml --durations=20 を実行してください。

トラブルシューティング

scaffold したプロジェクトの移動

uv sync は、venv の Python を指す絶対パスの shebang を持つ .venv/bin/* スクリプトを作成します。scaffold 後にリポジトリを移動すると（mv /old/path /new/path）、古い shebang が venv の site-packages とは異なるインタープリターを参照するため、uv run pytest は ModuleNotFoundError: No module named 'fastmcp' で失敗します。

修正方法：

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest も、一時的な回避策として使えます（古いエントリースクリプトの shim を介さずに実行します）。

copier update 後の uv.lock の更新

copier update によって新しい依存関係（pyproject.toml.jinja に追加された新しい extra など）が導入されると、CI のインストール手順で uv sync --locked が実行され、古いロックファイルに対して失敗します。ローカルで uv lock を実行し、copier-update PR を受け入れる際に、更新した uv.lock もコミットしてください。

CI では --locked を使ってインストールし（レビューのワークフローでは --frozen）、ジョブが自身のワークスペースで uv.lock を書き換えることはありません。再ロックするジョブは、修正したばかりのずれを隠してしまい、ワークスペースが変更されると同じジョブ内で後続の git checkout が失敗するためです。ロックファイルのずれは、ひそかな変更ではなく、明確なメッセージとともにインストール手順が失敗して示されます。

貢献

CONTRIBUTING.mdには、Issue とプルリクエストのルール、および修正をどこに配置するかが記載されています。ライブラリコードはfastmcp-pvl-core、テンプレートが管理するファイルはテンプレート、このリポジトリ内のDOMAIN-*／CONFIG-*／PROJECT-*ブロックに含まれるものはこのリポジトリが対象です。AGENTS.mdには規約と必須チェックが記載されています。.agents/skills/以下のスキルにはタスクの手順が記載されており、self-reviewing（プルリクエスト前のローカルでのセルフレビュー）、writing-release-notes（リリースノート）、applying-template-updates（毎週のテンプレート更新プルリクエスト）、authoring-issues-prs（Issue とプルリクエストの作成）などがあります。リリース手順は[docs/deployment/release-process.md](docs/deployment/release-process.md)、テンプレートの更新手順は[docs/deployment/template-updates.md](docs/deployment/template-updates.md)にあります。SECURITY.md`には、脆弱性を非公開で報告する方法と、その後の対応について記載されています。

リンク

• ドキュメント
• llms.txt
• FastMCP
• fastmcp-pvl-core

ドメイン設定

このプロジェクトのエントリーポイントとして用意されている変数です（ドメイン変数にはSCHOLAR_MCP_プレフィックスが付きます）。

変数	デフォルト	必須	説明
SCHOLAR_MCP_READ_ONLY	true	いいえ	trueの場合、書き込みタグ付きツール（PDFのダウンロードおよび変換キャッシュへの書き込み）は非表示になります。有効にするにはfalseを設定してください。
SCHOLAR_MCP_S2_API_KEY	(なし)	いいえ	Semantic Scholar APIキーです。任意ですが、強く推奨します。キーを使用すると、導入時に1 req/sの利用枠が適用されます。匿名ユーザーは共有の利用枠を使うため、リクエストが制限される場合があります。https://www.semanticscholar.org/product/api#api-key-form から申請してください。
SCHOLAR_MCP_DOCLING_URL	(なし)	いいえ	PDF変換に使用する、稼働中のdocling-serveインスタンスのベースURLです（例：http://localhost:5001）。未設定の場合、PDF変換ツールはエラーを返します。
SCHOLAR_MCP_CACHE_DIR	/data/scholar-mcp	いいえ	SQLiteキャッシュデータベース（cache.db）とダウンロードしたPDF（pdfs/, md/）を保存するディレクトリです。
SCHOLAR_MCP_CONTACT_EMAIL	(なし)	いいえ	OpenAlexのpolite poolで使用する連絡先メールアドレスです（レート制限が緩和されます）。PDFのフォールバックソースとしてUnpaywallの検索も有効になります。

これは厳選した一部です。tagsメタデータにreadmeが含まれるフィールドを掲載しています。すべてのドメイン変数は設定リファレンスに記載されており、設定ウィザードと同じグループ分けになっています。

ドメイン設定のフィールドは、src/scholar_mcp/config.pyのCONFIG-FIELDS-START／CONFIG-FIELDS-ENDセンチネルの間に定義されています。環境変数の読み取りにはfastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default)を使用し、命名規則を統一してください。フィールドの不変条件は、__post_init__内のCONFIG-VALIDATE-START／CONFIG-VALIDATE-ENDセンチネルの間に記述します。各フィールドのmetadataのhelp、tags、wizardグループからリファレンステーブルが直接生成されるため、内容を正確かつ完全に保ってください。

主な設計上の決定

• ライブラリ優先、MCP は任意です。 コアとなるドメインロジック（S2／EPO／Open Library／規格クライアント、エンリッチメントパイプライン、キャッシュ）は FastMCP なしでインポートできます。MCP サーバーは薄い非同期ラッパーです。スクリプト、ノートブック、その他のサーバーで再利用できます。
• ドメインコードは同期、MCP レイヤーは非同期です。 バックエンドクライアントは同期型です。MCP ツールは asyncio.to_thread() 経由で呼び出します。クライアントコードをシンプルにし、トランスポート境界で明示的に処理をオフロードします。
• テーブルごとの TTL と識別子エイリアスを備えた SQLite キャッシュです。 論文／著者の有効期間は 30 日、引用／参考文献は 7 日です。DOI ↔ S2 ID ↔ arXiv ID のエイリアスはキャッシュの消去後も保持されるため、エンリッチメントを繰り返しても同じ行にヒットします。
• デフォルトでは読み取り専用です。 書き込みを行うツール（PDF のダウンロード／変換、特許 PDF）は、SCHOLAR_MCP_READ_ONLY=false を設定しない限り非表示です。初回実行時の安全性を高めるデフォルト設定です。
• 時間のかかる処理はバックグラウンドジョブになります。 処理に時間がかかる可能性のある各ツールは、fastmcp-pvl-core のジョブレイヤーを使用します。SCHOLAR_MCP_JOBS_SOFT_DEADLINE_S より早く完了した呼び出しは結果を直接返し、それより時間がかかった場合は get_job_result でポーリングするためのハンドルを返します。S2 を利用するツールは、Semantic Scholar によるスロットリングが発生した場合も、理由を示すハンドルをすぐに返します。処理は中断した箇所から再開され、キャッシュにヒットした場合は引き続き結果を直接返します。
• EPO のスロットリングはキューに入れず、解除されるまで待ちます。 リクエストのたびにトラフィックライトを確認し、その結果を 1 分間キャッシュします。そのため、それより早く再試行しても、再度問い合わせるのではなくキャッシュを読み取ります。各バックオフ時間はキャッシュの有効期間を上回ります。1 日のクォータを使い切った場合は当日中に解除されないため、即座に報告します。
• Tier 2 の規格同期は帯域外で行います。 ISO／IEC／IEEE／CC／CEN のカタログは、実行時にライブで取得するのではなく、コミュニティ提供の Relaton ダンプから scholar-mcp sync-standards で取得します。これにより、ペイウォールのある HTML のスクレイピングを避け、ツール呼び出しを高速に保ちます。