SemanticScholar_MCP

Semantic Scholar の 3 つの API ファミリーに対する決定論的な Model Context Protocol インターフェース:

• S2AG — 学術グラフ検索、メタデータ、著者、引用、参考文献。

• Recommendations — Semantic Scholar の論文レコメンデーションサービス。

• Datasets — リリースの検出、データセットマニフェスト、増分データセット更新。

このプロジェクトは、エージェント型の文献調査システムではなく、意図的に薄い API ラッパーを提供します。

設計

中心となるルールは次のとおりです:

1 回の MCP ツール呼び出しは、1 つの文書化された Semantic Scholar 操作を表します。

サーバーは、検証、認証、レート制限、リトライ、レスポンス正規化などのトランスポートレベルの作業を実行します。

どの文献が科学的に重要かを判断することはありません。

例えば:

Agent
  │
  ├── "Search for paired-pulse TMS papers"
  │         │
  │         ▼
  │       S2AG MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  ├── "Recommend papers from these three seed papers"
  │         │
  │         ▼
  │  Recommendations MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  └── "Describe the latest S2ORC dataset release"
            │
            ▼
       Datasets MCP
            │
            ▼
       Semantic Scholar

検索拡張、科学的解釈、要約、引用グラフ探索戦略、研究総合は、利用側エージェントの責務のままです。

Related MCP server: Semantic Scholar MCP Server

リポジトリ構成

SemanticScholar_MCP/
├── src/
│   └── semantic_scholar_mcp/
│       ├── common/
│       │   ├── client.py
│       │   ├── errors.py
│       │   ├── models.py
│       │   ├── rate_limit.py
│       │   └── __init__.py
│       ├── datasets/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── recommendations/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── s2ag/
│       │   ├── server.py
│       │   └── __init__.py
│       └── __init__.py
├── tests/
├── AGENTS.md
├── CLAUDE.md
├── pyproject.toml
└── README.md

要件

• Python 3.11 以降

• Semantic Scholar へのインターネットアクセス

• 任意の Semantic Scholar API キー

実装は、公式の Python MCP SDK の現在の v2 系を使用しています。

インストール

仮想環境を作成します:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

開発用依存関係を含めて、パッケージを編集可能モードでインストールします:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

あるいは、uv を使用する場合:

uv venv --python 3.14
uv pip install -e ".[dev]"

Python 3.14 は必須ではありません。このプロジェクトは Python 3.11 以降をサポートしています。

Python パッケージ環境を構成した後、必要に応じてテストを実行します:

pytest
ruff check .
ruff format --check .

SEMANTIC_SCHOLAR_API_KEY をシステム環境変数としてすでに設定している場合(次のセクション 認証 を参照)、ライブ統合もテストできます:

pytest --run-integration

注: システム環境変数を API キーに設定したのが いずれかの VSCode ウィンドウを起動した後である場合、VSCode Extensions 経由で実行されるツールがシステム環境を取得できるようにするには、すべての VSCode ウィンドウを閉じて VSCode を完全に再起動する必要があります。

認証

Semantic Scholar は、多くの API 操作への未認証アクセスをサポートしています。

API キーが利用可能な場合は、次の方法で MCP プロセスに公開します:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

キーを次の場所に置かないでください:

• .mcp.json;

• .codex/config.toml;

• ソースコード;

• コミットされた .env ファイル;

• テストフィクスチャ。

MCP サーバーは、キーが存在する場合に自動的にそれを使用します。

認証が必要な操作は、キーが設定されていない場合に明示的なエラーを返す必要があります。

再度の注: システム環境変数を API キーに設定したのが いずれかの VSCode ウィンドウを起動した後である場合、VSCode Extensions 経由で実行されるツールがシステム環境を取得できるようにするには、すべての VSCode ウィンドウを閉じて VSCode を完全に再起動する必要があります。

ビルド更新

.\rebuild.ps1 と .\version.ps1 は、再ビルド時のバージョン更新を容易にするためのユーティリティとして提供されています:

rebuild.ps1

patch 番号を自動インクリメントせずに再ビルドするには、スイッチを明示的に指定します:

.\rebuild.ps1 -SkipVersionIncrement

それ以外の場合、.\rebuild.ps1 は pyproject.toml 内の patch 番号を直接自動インクリメントします。

version.ps1

再ビルドせずに <major> | <minor> | <patch> をインクリメントする場合:

.\version.ps1 patch -NoRebuild

minor バージョンをインクリメントし、patch を 0 にリセットして再ビルドする場合:

.\version.ps1 minor

major バージョンをインクリメントし、minor と patch の両方を 0 にリセットして再ビルドする場合:

.\version.ps1 major

MCP クライアント構成

3 つの Semantic Scholar MCP サーバーは、次のいずれかの方法で構成できます:

• プロジェクトローカル: 特定のリポジトリ内でのみ利用可能にします。または

• ユーザーグローバル: リポジトリをまたいで利用可能にします。

サーバーは次のとおりです:

• s2ag — Semantic Scholar Academic Graph

• s2_recommendations — Semantic Scholar Recommendations API

• s2_datasets — Semantic Scholar Datasets API

以下の例では、このリポジトリが次の場所にインストールされていることを前提としています:

C:\MyRepos\Python\SemanticScholar_MCP

必要に応じてパスを調整してください。

以下の例では、生成された semantic-scholar-*.exe コンソールランチャーを直接呼び出さずに、仮想環境の Python インタープリターを python -m ... で意図的に呼び出しています。これは Windows でのローカル開発中に推奨されます。コンソールランチャーを実行すると、編集可能な再インストール中に pip がそれらを置き換えられなくなる可能性があるためです。

Codex

Codex は、ユーザーグローバルとプロジェクトローカルの両方の config.toml ファイルをサポートしています。

プロジェクトローカルの Codex 構成

作成または編集:

<project>/.codex/config.toml

例:

[mcp_servers.s2ag]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.s2ag.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_recommendations]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.recommendations.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_datasets]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.datasets.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

プロジェクトスコープの Codex 構成は、Codex が信頼できると見なすプロジェクトに対してのみ読み込まれます。

ユーザーグローバルの Codex 構成

サーバーをプロジェクト横断で Codex から利用できるようにするには、同じ構成を次の場所に配置します:

~/.codex/config.toml

Windows では通常、次の場所です:

%USERPROFILE%\.codex\config.toml

例:

C:\Users\<username>\.codex\config.toml

MCP サーバーブロック自体は、上記のプロジェクトローカルの例と同じです。

Codex 構成の検証

ターミナルから:

codex mcp list

個々の登録は次のコマンドでも確認できます:

codex mcp get s2ag
codex mcp get s2_recommendations
codex mcp get s2_datasets

Claude Code

Claude Code は、プロジェクト共有とユーザースコープの MCP サーバーを区別します。

プロジェクトローカル / プロジェクト共有の Claude 構成

作成:

<project>/.mcp.json

内容:

{
  "mcpServers": {
    "s2ag": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.s2ag.server"
      ]
    },
    "s2_recommendations": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.recommendations.server"
      ]
    },
    "s2_datasets": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.datasets.server"
      ]
    }
  }
}

MCP 構成をそのリポジトリの他のユーザーと共有する場合は、このファイルを利用側リポジトリにコミットできます。

ユーザーグローバルの Claude 構成

グローバルな Claude Code 構成では、ユーザースコープの MCP 登録を Claude Code に管理させる方法が推奨されます。

実行:

claude mcp add --scope user s2ag -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.s2ag.server

claude mcp add --scope user s2_recommendations -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.recommendations.server

claude mcp add --scope user s2_datasets -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.datasets.server

Claude Code は現在、ユーザースコープの MCP 構成を次の場所に保存します:

~/.claude.json

Windows の場合:

%USERPROFILE%\.claude.json

claude mcp add --scope user を使用する方法は、このファイルを手動で編集するよりも推奨されます。Claude Code が .claude.json 内に追加の状態を保持しているためです。

登録を確認するには:

claude mcp list

特定の Claude Code バージョンでユーザースコープの MCP サーバーの読み込みに問題がある場合は、プロジェクトの .mcp.json 構成が最も簡単な代替手段です。

Semantic Scholar API キー

多くの Semantic Scholar 操作は認証なしで動作できます。API キーを必要とする操作では次を使用します:

SEMANTIC_SCHOLAR_API_KEY

キーを MCP 構成ファイルにコミットしないでください。

Windows では、ユーザー環境変数として永続化できます:

[Environment]::SetEnvironmentVariable(
    "SEMANTIC_SCHOLAR_API_KEY",
    "YOUR_API_KEY",
    "User"
)

変数を設定した後、VS Code、Codex、Claude Code、その他の MCP ホストを再起動して、新しく起動される MCP プロセスがそれを継承するようにしてください。

MCP サーバーは、キーが存在する場合は自動的にそれを使用し、存在しない場合は、Semantic Scholar が匿名アクセスを許可している箇所では未認証のまま動作します。

プロジェクトローカルとユーザーグローバルの比較

有用な基準は次のとおりです:

調査エージェントが明示的に文献発見を実行することが期待される研究リポジトリでは、利用可能な調査ツールがリポジトリとともに移動するため、通常はプロジェクトローカル構成の方が適しています。

任意のプロジェクトから Semantic Scholar への一般的な個人アクセスには、ユーザーグローバル構成の方が便利です。

共有レート制限

Semantic Scholar の入門用認証済みレート制限は、各 MCP サーバーに独立して適用されるのではなく、API エンドポイント全体に適用されます。

そのため、このリポジトリは共有のプロセス間リミッターを使用します:

S2AG MCP ────────────────┐
                         │
Recommendations MCP ─────┼── shared limiter ──> Semantic Scholar
                         │
Datasets MCP ────────────┘

デフォルトの実装では、3 つのローカルサーバー全体で、1 秒あたりおよそ 1 回以下のアップストリームリクエストを許可する必要があります。

これは、複数のホストが同時に実行されている場合に重要です。例えば:

VS Code / Codex
Claude Code
MCP Inspector
tests

リミッターは、各プロセスで独立したクロックを維持するのではなく、これらのプロセスを調整する必要があります。

リトライ動作

一時的なアップストリーム障害は、上限付きの指数バックオフを使用してリトライできます。

例:

• HTTP 429;

• 一時的な 5xx レスポンス;

• 一時的なネットワーク障害。

Retry-After が指定されている場合は、それが尊重されます。

無効なリクエスト、拒否された認証、リソースの欠落などの通常のクライアントエラーは、繰り返しリトライされません。

リトライには上限があります。MCP が無期限にリトライすることはありません。

S2AG MCP

実行:

semantic-scholar-s2ag

または:

python -m semantic_scholar_mcp.s2ag.server

初期の API サーフェスには次のものが含まれる予定です:

ページネーションは明示的なままです。

引用リクエストは引用グラフを再帰的に辿りません。

検索は自動的にフォローアップ検索を発行しません。

Recommendations MCP

実行:

semantic-scholar-recommendations

または:

python -m semantic_scholar_mcp.recommendations.server

初期のサーフェスは意図的に小さくなっています:

サーバーは、呼び出し側が選択したシードを Semantic Scholar に渡します。

サーバー自身がシードを選択したり、結果に 2 回目の LLM 生成ランキングを適用したりすることはありません。

概念的なワークフローの例:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

実行:

semantic-scholar-datasets

または:

python -m semantic_scholar_mcp.datasets.server

初期ツールは次のとおりです:

Datasets MCP は、Semantic Scholar のデータセット全体を自動的にダウンロードすることは意図的にありません。

一部の Semantic Scholar データセットは非常に大きくなっています。マニフェストの取得は適切な MCP 操作ですが、数ギガバイトのコーパスのダウンロードを開始するには、ユーザーが明示的に制御できるツールが必要です。

将来の専用 CLI は、次のようなコマンドを提供するかもしれません:

s2-dataset download ...
s2-dataset update ...
s2-dataset verify ...

それらの操作を暗黙の MCP 動作にすることなく。

決定性

このプロジェクトにおいて、決定性とはツールのセマンティクスが明示的かつ検査可能であることを意味します。

ツールは次のことを行う場合があります:

validate input
    ↓
wait for rate limiter
    ↓
make one documented API request
    ↓
retry transient transport failures if necessary
    ↓
normalize response
    ↓
return structured data

ツールが暗黙のうちに次のようになってはなりません:

search
   ↓
search again with different terms
   ↓
fetch every page
   ↓
walk citations
   ↓
request recommendations
   ↓
rank with an LLM
   ↓
summarize papers

より高レベルのオーケストレーションは、このリポジトリの外部に属します。

ページネーション

ページネーションは呼び出し側が制御します。

Semantic Scholar が継続トークン、オフセット、または同等のカーソルを返す場合、MCP はその値を返します。

呼び出し側は明示的に次のページをリクエストできます。

MCP は利用可能なすべてのページを自動的に取得しません。

これにより、決定性と API 使用量の両方が保護されます。

フィールド

Semantic Scholar が明示的なレスポンスフィールドをサポートしている場合、ツールは呼び出し側が必要とするフィールドのみをリクエストする必要があります。

使いやすさのために、小さなデフォルトのフィールドセットが提供される場合があります。

抄録や引用コンテキストなどの大きなフィールドは、文書化されたツールのデフォルトの一部でない限り、自動的にリクエストすべきではありません。

エラー

アップストリームの状態は、安定した理解しやすい MCP エラーに変換されるべきです。

例:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

有用な場合、構造化エラーは次のものを保持することがあります:

• HTTPステータス；

• 再試行可能性；

• 試行回数；

• Semantic Scholarのエラーメッセージ。

シークレットを絶対に含めてはなりません。

開発

単体テストを実行：

pytest

Lintを実行：

ruff check .

フォーマットを確認：

ruff format --check .

フォーマットを適用：

ruff format .

Semantic Scholarのライブテストは別途マークされています：

pytest --run-integration

通常の単体テストはHTTP通信をモックし、Semantic Scholar APIのクォータを消費してはなりません。

テスト方針

最も重要なテストはAPI忠実性を検証することです。

すべてのMCPツールについて、テストは以下を確認する必要があります：

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

テストはまた、隠れた動作がないことも検証する必要があります。

例えば、1回の引用リクエストは1回の引用API操作を生成すべきであり、後続のページや参考文献を自動的にリクエストしてはなりません。

研究ツールとの関係

このリポジトリはドメイン中立のままでなければなりません。

例えば、以下を公開できます：

paper A cites paper B

または：

Semantic Scholar recommends paper C from seeds A and B

しかし、以下のように結論づけてはなりません：

paper C is the strongest evidence for a particular neuroscience hypothesis

別の研究リポジトリ、Research MCP、または人間の研究者がその解釈を行うことができます。

この分離により、Semantic Scholarレイヤーは以下を維持できます：

• 決定論的；

• 再利用可能；

• テストが容易；

• 特定の科学分野に依存しない；

• さまざまなMCPホストおよびエージェントで利用可能。

Semantic Scholarの利用

このプロジェクトは正当な研究目的での使用を意図しており、現在のSemantic Scholar APIライセンスおよびドキュメントに準拠する必要があります。

APIの利用は以下を行うべきです：

• アクティブなレート制限を尊重する；

• 適切な場合はバッチ/一括操作を使用する；

• 必要なフィールドのみをリクエストする；

• 上限付き指数バックオフを使用する；

• API資格情報を保護する；

• 無制限のAPIクローリングを避ける；

• 本当にコーパス規模のアクセスが必要な場合は、Datasets APIを優先する。

Semantic Scholarの応答データを使用する公開製品または表示には、追加の帰属表示要件がある場合があります。公開向けのデータ表示を追加する前に、現在のSemantic Scholarライセンスを確認してください。

このリポジトリの規範的な開発およびAPI使用ルールについては、AGENTS.mdを参照してください。