Semantic Scholar MCP Server

Semantic Scholar MCP サーバー

Semantic Scholar API 用の FastMCP サーバー実装です。学術論文データ、著者情報、引用ネットワークに包括的にアクセスできます。

Claude Code のスキルをお探しですか？ semantic-scholar-skills をご覧ください。この次世代ツールキットには、この MCP サーバーと、すぐに使える Claude Code スキル（/expand-references、/trace-citations、/paper-triage）、および Python ワークフローエンジンがまとめられています。

プロジェクト構成

保守性を高めるため、プロジェクトはモジュール式の構成にリファクタリングされています。

semantic-scholar-server/
├── semantic_scholar/            # Main package
│   ├── __init__.py             # Package initialization
│   ├── server.py               # Server setup and main functionality
│   ├── mcp.py                  # Centralized FastMCP instance definition
│   ├── config.py               # Configuration classes
│   ├── utils/                  # Utility modules
│   │   ├── __init__.py
│   │   ├── errors.py           # Error handling
│   │   └── http.py             # HTTP client and rate limiting
│   ├── api/                    # API endpoints
│       ├── __init__.py
│       ├── papers.py           # Paper-related endpoints
│       ├── authors.py          # Author-related endpoints
│       └── recommendations.py  # Recommendation endpoints
├── run.py                      # Entry point script

この構成には、次の利点があります。

• 機能を論理的なモジュールに分割します
• コードベースの理解と保守を容易にします
• テストや将来の拡張をより容易にします
• 関連する機能をまとめて管理します
• 循環インポートを避けるため、FastMCP インスタンスを一元管理します

機能

• 論文の検索と発見

  • 高度なフィルタリングに対応した全文検索
  • タイトルに基づく論文の照合
  • 論文の推薦（単一および複数の論文）
  • 論文詳細の一括取得
  • ランキング戦略を利用した高度な検索

• 引用分析

  • 引用ネットワークの探索
  • 参考文献の追跡
  • 引用コンテキストと影響の分析

• 著者情報

  • 著者の検索とプロフィールの詳細
  • 出版履歴
  • 著者詳細の一括取得

• 高度な機能

  • 複数のランキング戦略を用いた複雑な検索
  • フィールド選択のカスタマイズ
  • 効率的な一括処理
  • レート制限への準拠
  • 認証あり、認証なしの両方のアクセスに対応
  • グレースフルシャットダウンとエラー処理
  • コネクションプーリングとリソース管理

システム要件

• Python 3.10+
• API キー用の環境変数（任意）

インストール

クイックインストール（PyPI）

pip install semantic-scholar-fastmcp

または、uvx で直接実行します。

uvx semantic-scholar-fastmcp

MCP クライアントの設定

uvx に対応するすべての MCP クライアントで使用できます。

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["semantic-scholar-fastmcp"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Smithery 経由でインストール

Smithery を使って、Semantic Scholar MCP Server を Claude Desktop に自動的にインストールするには、次の手順を実行します。

npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude

手動インストール

1. リポジトリをクローンします。

git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git
cd semantic-scholar-fastmcp-mcp-server

2. 開発モードでインストールします。

pip install -e ".[dev]"

3. サーバーを起動します。

semantic-scholar-mcp-server

API キー（任意）

より高いレート制限と優れたパフォーマンスを利用するには、次の手順を実行します。

1. Semantic Scholar API から API キーを取得します
2. 上記の env セクションに示すように、FastMCP の設定に追加します

API キーが指定されていない場合、サーバーはレート制限の低い、認証なしのアクセスを使用します。

設定

貢献

CONTRIBUTING.md を参照してください。

環境変数

• SEMANTIC_SCHOLAR_API_KEY：Semantic Scholar API キー（任意）
  • Semantic Scholar API からキーを取得してください
  • 指定されていない場合、サーバーは認証なしのアクセスを使用します

HTTP ブリッジ（組み込み）

このリポジトリには、一般的なワークフロー向けの最小限の REST API を公開する、小規模な HTTP ブリッジ（semantic_scholar.bridge）が含まれています。

デフォルトのリッスンポート：8000。

環境変数によるブリッジの設定：

• SEMANTIC_SCHOLAR_ENABLE_HTTP_BRIDGE（デフォルト：1） — 無効にするには 0 に設定します
• SEMANTIC_SCHOLAR_HTTP_BRIDGE_HOST（デフォルト：0.0.0.0）
• SEMANTIC_SCHOLAR_HTTP_BRIDGE_PORT（デフォルト：8000）

利用可能なエンドポイント：

• GET /v1/paper/search?q=... — 論文検索（パラメーター：fields、offset、limit）
• GET /v1/paper/{paper_id} — 論文の詳細（パラメーター：fields）
• POST /v1/paper/batch — 論文の一括詳細取得（JSON：{ "ids": [ ... ] }）
• GET /v1/author/search?q=... — 著者検索（パラメーター：fields、offset、limit）
• GET /v1/author/{author_id} — 著者の詳細（パラメーター：fields）
• POST /v1/author/batch — 著者の一括詳細取得（JSON：{ "ids": [ ... ] }）
• GET /v1/recommendations?paper_id=... — 論文の推薦

このブリッジは、パッケージの HTTP ユーティリティ（semantic_scholar.utils.http）を再利用するため、レート制限、API キーの処理、コネクションプーリングは MCP ツールと一貫しています。

例：

curl 'http://localhost:8000/v1/paper/search?q=machine+learning&limit=5'

レート制限

サーバーは適切なレート制限に自動的に調整します。

API キーあり：

• 検索、一括取得、推薦の各エンドポイント：1 秒あたり 1 リクエスト
• その他のエンドポイント：1 秒あたり 10 リクエスト

API キーなし：

• すべてのエンドポイント：5 分あたり 100 リクエスト
• リクエストのタイムアウト時間が長くなります

注：レート制限は変更される場合があります。最新情報は Semantic Scholar API をご覧ください。

Semantic Scholar API の利用規約

このプロジェクトは、Allen Institute for AI（AI2）が提供する Semantic Scholar Academic Graph API を使用しています。 使用する前に、API License Agreement をご確認ください。

利用可能な MCP ツール

サーバーは現在、16 個の MCP ツールを公開しています。

注：すべてのツールは、公式の Semantic Scholar API ドキュメント に準拠しています。フィールドの詳細な仕様と最新情報については、公式ドキュメントをご覧ください。

論文検索ツール

• paper_relevance_search：関連度順で論文を検索します

  • 年の範囲や引用数による絞り込みなど、包括的なクエリパラメーターに対応しています
  • カスタマイズ可能なフィールドを指定して、ページ分割された結果を返します

• paper_bulk_search：並べ替えオプションを使用して論文を一括検索します

  • 関連度検索と同様ですが、より大規模な結果セットに最適化されています
  • 引用数や出版日などによる並べ替えに対応しています

• paper_title_search：完全一致するタイトルで論文を検索します

  • タイトルがわかっている特定の論文を探すのに便利です
  • カスタマイズ可能なフィールドを指定して、論文の詳細情報を返します

• paper_details：特定の論文に関する包括的な詳細情報を取得します

  • さまざまな論文 ID 形式（S2 ID、DOI、ArXiv など）を受け付けます
  • ネストされたフィールドにも対応し、詳細な論文メタデータを返します

• paper_batch_details：複数の論文の詳細情報を効率よく取得します

  • 1 回のリクエストで最大 1000 件の論文 ID を受け付けます
  • 単一論文の詳細取得と同じ ID 形式およびフィールドに対応しています

• paper_authors：特定の論文に関連付けられた著者を取得します

  • 論文の著者をページ分割して返します
  • offset と limit の制御により、著者フィールドをカスタマイズできます

• paper_autocomplete：入力途中のクエリに対する論文タイトルの候補を取得します

  • インタラクティブな検索補完に必要な最小限の論文メタデータを返します
  • API がサポートする長さを超えるクエリは切り詰められます

• snippet_search：論文のスニペットや抜粋を検索します

  • タイトル、要旨、本文から関連するテキストの一致箇所を返します
  • 論文 ID、著者、掲載先、年、研究分野による絞り込みに対応しています

引用ツール

• paper_citations：特定の論文を引用している論文を取得します

  • 引用論文のページ分けされたリストを返します
  • 利用可能な場合は、引用の文脈を含めます
  • フィールドのカスタマイズと並べ替えに対応しています

• paper_references：特定の論文が参照している論文を取得します

  • 参考文献のページ分けされたリストを返します
  • 利用可能な場合は、参照の文脈を含めます
  • フィールドのカスタマイズと並べ替えに対応しています

著者ツール

• author_search：名前で著者を検索します

  • カスタマイズ可能なフィールドを含むページ分けされた検索結果を返します
  • 所属機関と出版物数を含めます

• author_details：著者の詳細情報を取得します

  • 著者の包括的なメタデータを返します
  • h-indexや引用数などの指標を含めます

• author_papers：著者が執筆した論文を取得します

  • 著者の出版物のページ分けされたリストを返します
  • フィールドのカスタマイズと並べ替えに対応しています

• author_batch_details：複数の著者の詳細情報を取得します

  • 最大1000人の著者の情報を効率的に取得します
  • 単一の著者詳細と同じフィールドを返します

推薦ツール

• get_paper_recommendations_single：単一の論文に基づいて推薦を取得します

  • 内容と引用パターンに基づいて類似した論文を返します
  • 推薦論文のフィールドをカスタマイズできます

• get_paper_recommendations_multi：複数の論文に基づいて推薦を取得します

  • 肯定例と否定例の論文を受け付けます
  • 肯定例に類似し、否定例とは類似しない論文を返します

使用例

基本的な論文検索

results = await paper_relevance_search(
    context,
    query="machine learning",
    year="2020-2024",
    min_citation_count=50,
    fields=["title", "abstract", "authors"]
)

論文の推薦

# Single paper recommendation
recommendations = await get_paper_recommendations_single(
    context,
    paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
    fields="title,authors,year"
)

# Multi-paper recommendation
recommendations = await get_paper_recommendations_multi(
    context,
    positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    negative_paper_ids=["ArXiv:1805.02262"],
    fields="title,abstract,authors"
)

バッチ操作

# Get details for multiple papers
papers = await paper_batch_details(
    context,
    paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    fields="title,authors,year,citations"
)

# Get details for multiple authors
authors = await author_batch_details(
    context,
    author_ids=["1741101", "1780531"],
    fields="name,hIndex,citationCount,paperCount"
)

エラー処理

サーバーは標準化されたエラーレスポンスを提供します。

{
    "error": {
        "type": "error_type",  # rate_limit, api_error, validation, timeout
        "message": "Error description",
        "details": {
            # Additional context
            "authenticated": true/false  # Indicates if request was authenticated
        }
    }
}