scholar

Scholar MCP Server

科学文献データベースへの構造化されたアクセスを提供する、Model Context Protocol（MCP）サーバーです。Scopus、OpenAlex、Semantic Scholar、Unpaywallへの統一インターフェースとして機能し、AI エージェントによる体系的な論文検索、著者の名寄せ、引用系譜の追跡、マルチモーダルなコンテンツ抽出を可能にします。

主な機能

• 統合文献検索

  • Semantic Scholar 連携 — 関連度の高い検索と、AI が生成するTLDRを含む詳細なメタデータを提供します（API キーが必要です）。
  • Scopus 連携 — 高度なブール構文を使った、対象を絞ったメタデータの取得に対応します（API キーが必要です）。
  • OpenAlex 連携 — 2億5,000万件以上の論文を幅広く検索し、抄録を再構成します。
  • Unpaywall による解決 — DOI と、世界各地のオープンアクセスリポジトリにある PDF を照合します。
  • Sci-Hub によるフォールバック（⚠️ 注意して使用してください） — ペイウォールを回避するため、ミラーを自動で解決し、解析します。

• 書籍の検索と抽出

  • Google Books と Open Library — API キー不要で、書籍のメタデータ、版、説明を検索できます。
  • Library Genesis（Libgen） — PyMuPDF を使って書籍を直接検索し、全文を抽出します。スマートキャッシュと、目次の読み取り、キーワードを指定した検索、ページ範囲の抽出などのトークン節約機能を備えています。

• 著者の特定と指標

  • OpenAlex のオートコンプリートを使って、著者の名寄せと ID の解決をすばやく行います。
  • H-index、i10-index、所属機関の履歴、ORCID との連携を含む、包括的なプロフィールを提供します。
  • Elsevier（Scopus）による精度の高い指標で、検証済みの出版物数を確認できます。

• 引用系譜の追跡

  • 前方引用（引用している論文）と後方参照（引用されている論文）を通じて、研究の変遷をたどれます。

• 構造化・マルチモーダル抽出

  • テキスト抽出 — PyMuPDF を使い、レイアウトを考慮してオープンアクセス PDF を解析します。
  • 画像レンダリング — LLM による図表や数式の分析向けに、ページごとに PNG でレンダリングします。
  • HTML フォールバック — BeautifulSoup を使って、ウェブベースの研究リソースから抽出します。

• トピックのマッピングと分野分析

  • 概念と分野の階層を特定し、研究領域をマッピングします。
  • 大量の文献を処理するためのメタデータの一括取得に対応します（1 リクエストあたり最大 50 件の DOI）。

• アクセス管理とフォールバック

  • アクセス制限のあるコンテンツを自動で検出し、手動アップロードのための人間参加型の手順を提示します。

アーキテクチャ

graph TD
    A[LLM Agent] -->|MCP Protocol| B(Scholar MCP Server)
    B --> C{Database Router}
    C -->|Primary| D[Scopus API]
    C -->|Fallback| E[OpenAlex API]
    C -->|DOI Resolver| F[Unpaywall API]
    C -->|Citations| P[CrossRef API]
    
    D --> G{Access Check}
    E --> G
    F --> G
    P --> G
    
    G -->|Open Access| H[PDF Buffer Download]
    G -->|Closed Access| I[Human-in-the-Loop Prompt]
    H --> J[PyMuPDF Text Extractor]
    H --> K[PyMuPDF Vision Renderer]
    J --> L[Return Context to LLM]
    K --> L
    I --> L
    B --> M{Author Router}
    M -->|Profile| N[OpenAlex Authors API]
    M -->|Metrics| O[Scopus Author API]
    N --> L
    O --> L

インストール

クイックスタート（PyPI 経由）

サーバーを最も手早く利用するには、PyPI 経由で直接実行します。

pip install scholar-academic-mcp

手動セットアップ（開発用）

# Clone the repository
git clone https://github.com/mlintangmz2765/Scholar-MCP.git
cd Scholar-MCP

# Setup virtual environment
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate # Unix

# Install in editable mode
pip install -e .

環境変数

変数	必須	説明
SCOPUS_API_KEY	はい	Scopus の検索と著者情報の取得に使う Elsevier API キーです。
S2_API_KEY	いいえ	TLDR と S2 グラフへのアクセスに使う Semantic Scholar API キーです。
SCIHUB_MIRRORS	いいえ	PDF のフォールバックに使う、稼働中の Sci-Hub ミラーのカンマ区切りリストです。
LIBGEN_MIRRORS	いいえ	稼働中の Library Genesis ミラーのカンマ区切りリストです。
SCOPUS_INST_TOKEN	いいえ	Scopus 経由で抄録全文にアクセスするための機関トークンです。
CONTACT_EMAIL	はい	OpenAlex／Unpaywall の礼儀正しい利用者向け API ルーティングに使うメールアドレスです。

設定

Claude Desktop / Cursor

設定ファイル（例：claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "scholar-academic-mcp": {
      "command": "scholar-academic-mcp",
      "env": {
        "SCOPUS_API_KEY": "your_scopus_api_key",
        "S2_API_KEY": "your_s2_api_key",
        "SCIHUB_MIRRORS": "https://sci-hub.ru,https://sci-hub.st",
        "LIBGEN_MIRRORS": "https://libgen.la,http://libgen.li",
        "SCOPUS_INST_TOKEN": "your_optional_inst_token",
        "CONTACT_EMAIL": "[email protected]"
      }
    }
  }
}

クイックスタートと使用例

設定が完了すると、AI エージェントは複雑なリサーチのワークフローを実行できます。以下に、ツールへの入力と構造化された出力の代表例を示します。

1. 文献の発見（Scopus）

プロンプト："Scopus を使って、2022 年以降に発表された「Transformer architectures」に関する最近の論文を探してください。"

ツール呼び出し：search_papers_tool(query="TITLE-ABS-KEY(Transformer architectures) AND PUBYEAR > 2022", limit=3)

出力：

Found 3 papers via Scopus:
- [SCOPUS_ID:85184...] Attention is All You Need? A Survey of Transformer Variants
  Authors: Smith, J., Doe, A.
  Date: 2024-01-15 | DOI: 10.1016/j.artint.2023.104012

2. マルチモーダルコンテンツ分析

プロンプト："この URL の 3 ページ目にあるニューラルネットワークのアーキテクチャ図を見たいです。"

ツール呼び出し：get_full_text_visual_tool(url="https://arxiv.org/pdf/1706.03762.pdf", max_pages=3)

出力：

• [Text] 「3 ページを視覚的にレンダリングしました……」
• [Image]（1 ページ目の PNG データ）
• [Image]（2 ページ目の PNG データ）
• [Image]（アーキテクチャ図が含まれる 3 ページ目の PNG データ）

3. 研究トピックのマッピング

プロンプト："「Generative AI」に関連するサブフィールドや領域について理解できるようにしてください。"

ツール呼び出し：search_topics_tool(query="Generative AI")

出力：

Found 1 topics for 'Generative AI':
- Artificial Intelligence
  Hierarchy: Computer Science → Artificial Intelligence → Machine Learning
  Works: 12,450 | Citations: 450,210
  Description: A field of computer science that focuses on creating systems capable of generating...

ツール

サーバーは、7 つのカテゴリにわたって 23 個のツールを登録します。

論文の検索

ツール	シグネチャ	説明
search_papers_tool	(query, limit=5, use_scopus=True, sort_by="relevance")	Scopus（ブール構文）または OpenAlex を使って論文を検索します。cited_by_count または publication_year で並べ替えます。
search_papers_s2_tool	(query, limit=5)	Semantic Scholar を使って論文を検索します。注：レート制限により、リクエストは厳密に 1 秒あたり 1 回までです。
get_paper_details_tool	(paper_id)	Scopus ID、DOI、または OpenAlex ID を使って、完全なメタデータと要約を取得します（自動ルーティング対応）。
get_paper_details_s2_tool	(paper_id)	AI 生成の TLDRを含む、Semantic Scholar の完全なメタデータを取得します。S2 ID または DOI を指定できます。
search_titles_unpaywall_tool	(query, is_oa=None)	Unpaywall のデータベースをタイトルで直接検索します。OA の結果のみを取得するには、is_oa=True を設定します。
get_related_works_tool	(paper_id, limit=10)	OpenAlex の書誌結合を使って、関連する論文や類似論文を検索します。

書籍の発見と抽出

ツール	シグネチャ	説明
search_books_tool	(query, limit=5, source="googlebooks")	Google Books または Open Library で書籍のメタデータを検索します。
get_book_details_tool	(book_id, source="googlebooks")	書籍の詳細情報、説明、ISBN を取得します。
search_libgen_tool	(query, limit=5)	Library Genesis で書籍を検索し、ダウンロード用の MD5 ハッシュを取得します。
interact_with_book_tool	(md5, action, keyword, start_page, end_page)	Libgen からスマートに情報を抽出します。アクション：toc（目次）、search（キーワード）、pages（ページ範囲）。

著者分析

ツール	シグネチャ	説明
autocomplete_authors_tool	(name, limit=5)	著者名をすばやく識別し、OpenAlex の著者 ID を特定します。
search_authors_tool	(name, institution=None, limit=5)	H-index、i10-index、ORCID、研究概念など、詳細な計量書誌学的プロフィールを取得します。
search_author_by_orcid_tool	(orcid)	ORCID（生の形式または URL 形式）で著者を直接検索します。
retrieve_author_works_tool	(author_id, limit=15)	指定した OpenAlex の著者の出版物を時系列順に取得します。
get_author_profile_scopus_tool	(author_id)	Scopus 由来の正確な h-index、引用数、所属先を取得します。
get_author_profile_s2_tool	(author_id)	Semantic Scholar の著者プロフィール（H-index、論文数、引用数）を取得します。

引用の追跡

ツール	シグネチャ	説明
get_citations_tool	(paper_id, direction="references")	OpenAlex を介して、後続の引用または先行する参考文献を取得します。

全文と PDF

ツール	シグネチャ	説明
get_full_text_tool	(url, start_page=None, end_page=None)	OA PDF または HTML ページからテキストを抽出します。ページ範囲を指定できます。
get_full_text_visual_tool	(url, max_pages=3)	PDF ページを画像としてレンダリングし、Vision 対応 LLM で利用できるようにします。
fetch_pdf_text_unpaywall_tool	(doi)	すべてを一括処理します：Unpaywall で DOI を解決 → PDF をダウンロード → テキストを抽出します。
get_scihub_link_tool	(doi)	Sci-Hub を使って、厳格なペイウォールのある DOI を無料の直接 PDF リンクに解決しようとします。
fetch_pdf_text_scihub_tool	(doi)	バイパス処理を一括で行います：Sci-Hub で DOI を解決 → PDF をダウンロード → テキストを抽出します。

引用と執筆

ツール	シグネチャ	説明
get_bibtex_tool	(doi)	CrossRef のコンテンツネゴシエーションを通じて、LaTeX 用の BibTeX エントリを生成します。
format_citation_tool	(doi, style="apa")	APA、IEEE、Chicago、Harvard、Vancouver、MLA、または Turabian 形式で引用を整形します。

オープンアクセスの解決

ツール	シグネチャ	説明
get_unpaywall_link_tool	(doi)	Unpaywall を通じて、DOI に対応する利用可能なすべての OA の提供元を解決します。

トピックのマッピングと一括分析

ツール	シグネチャ	説明
search_topics_tool	(query, limit=10)	研究トピックや概念を閲覧します。分野、領域、出版物数を返します。
batch_lookup_tool	(dois: list[str])	1 回の呼び出しで複数の DOI のメタデータを一括取得します（最大 50 件）。

技術設計と信頼性

Scholar MCP は、重要な研究環境における精度と耐障害性を重視して設計されており、データの完全性を確保するために複数の保護層を備えています。

• 厳格なデータ契約（Pydantic）

  • すべての上流 API レスポンスは、エージェントに返される前に Pydantic モデルで検証されます。
  • 上流データベースのスキーマが変更されても、予測可能で型安全なインターフェイスを保証します。

• 耐障害性に優れたネットワーク（Tenacity）

  • 一時的な HTTP エラー（429、5xx）に対して、tenacity を使用した 指数バックオフ を統合しています。
  • Elsevier と OpenAlex の「polite pool」ルーティングに対応した、設定可能なレート制限の認識機能を備えています。

• リソースの安全性と並行処理

  • コンテキスト管理される抽出器：PDF バッファーとファイル記述子を自動的にクリーンアップします。
  • 分離された並行処理：バッチ操作では asyncio.gather と局所的な例外処理を使用し、セッション全体の失敗を防ぎます。

• システムの可観測性

  • 構造化された標準エラー出力（stderr）のログにより、MCP JSON-RPC プロトコルに干渉することなく、ツールのライフサイクル全体で実行状況を確認できます。

• 自動検証

  • respx を活用した包括的なテストスイートにより、API を決定論的にモックし、ネットワークに依存せずにエッジケースを 100％カバーします。

プロジェクト構成

Scholar-MCP/
├── .github/workflows/ # GitHub Actions (CI & Releases)
├── scripts/           # Automation & Validation scripts
├── tests/             # Pytest suite (respx mocked)
├── server.py          # FastMCP tool entry point
├── api.py             # API Clients (Scopus, OpenAlex, Unpaywall, CrossRef)
├── extractor.py       # PDF/HTML Extraction & Rendering
├── models.py          # Pydantic Data Validation
├── server.json        # MCP Registry Manifest
├── pyproject.toml     # Python packaging configuration
├── requirements.txt   # Dependencies
├── VERSION            # Version tracking (v1.0.0)
├── LICENSE            # MIT License
├── README.md          # Documentation
├── .env.example       # Template for API keys
└── .gitignore         # Git exclusion rules

トラブルシューティング

症状	原因	解決方法
Scopus からの HTTP 401	標準の API キーには META_ABS ビューへのアクセス権がありません。	SCOPUS_INST_TOKEN を設定するか、代替として OpenAlex を使用してください。
PDF ダウンロード時の HTTP 403	出版社のボット対策（Cloudflare、DataDome）。	PDF を LLM に手動で提供してください。
Unpaywall の検索結果が空	論文が厳格なペイウォールの背後にあり、OA 版がありません。	ResearchGate または機関経由で、著者に PDF を依頼してください。
SCOPUS_API_KEY is not set	環境変数が設定されていません。	.env が設定されていることを確認するか、MCP クライアントの env ブロック経由で渡してください。

貢献

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/my-feature）。
3. 変更をコミットします（git commit -m 'feat: add new capability'）。
4. ブランチにプッシュします（git push origin feature/my-feature）。
5. プルリクエストを作成します。

すべてのコードが PEP 8 規約に従っていることを確認してください。

ライセンス

MIT License。詳細は LICENSE を参照してください。

---

免責事項： 出版社の API に対する自動クエリは、Elsevier、OpenAlex、Unpaywall それぞれの利用規約に従う必要があります。API キーを配布しないでください。適用されるすべてのレート制限を遵守してください。

mcp-name: io.github.mlintangmz2765/scholar