Paper Search Mcp

Paper Search MCP

複数のソースから学術論文を検索、ダウンロードするための Model Context Protocol（MCP）サーバーです。このプロジェクトでは無料を優先する方針を採用しています。オープンデータと公開データのソースを優先し、安定性やカバレッジの向上に役立つ場合は任意の API キーをサポートするとともに、上級ユーザー向けにソース固有のコネクターを拡張できるようにしています。

---

目次

• 概要
• プロジェクトの原則
• MCP 認証の互換性
• 機能
• ソース戦略
• Sci-Hub に関する注意
• インストール
  • Claude Code（Skill）
  • 方法 1 — Smithery
  • 方法 2 — uvx
  • 方法 3 — uv
  • 方法 4 — pip
  • 方法 5 — npx
  • 方法 6 — Docker
  • 方法 7 — ソースをクローンして実行
  • DeepSeek Harness（DSH）
  • 環境変数
• コントリビューション
• デモ
• スター履歴
• ライセンス
• TODO

---

概要

paper-search-mcp は、さまざまなプラットフォームから学術論文を検索、ダウンロードするための Python ベースのツールです。論文の検索、PDF のダウンロード、テキストの抽出を行うツールを提供しており、研究者や AI を活用したワークフローに最適です。MCP サーバー（Claude Desktop およびその他の MCP クライアント向け）として、または CLI インターフェイスを備えた Claude Code のスキルとして使用できます。

プロジェクトの原則

• 無料を優先：公開ソースとオープンソースを標準のロードマップとします。有料またはアクセス制限のあるソースは、このプロジェクトの中心的な方向性ではありません。
• 任意の API キー：API キーは、安定性、レート制限、メタデータの品質を向上できる場合にのみサポートします。可能な限り、API キーなしでも MCP を使用できるようにします。
• LLM に適した検索結果の取得：検索結果を標準化し、重複を排除して、後続の LLM ワークフローでできる限り完全に利用できるようにします。
• ソースの透明性：ソースごとに強みが異なります。すべてのソースが全文検索に対応しているかのように装うのではなく、MCP でそれぞれのトレードオフを明示します。

---

MCP 認証の互換性

同梱の MCP サーバーは、stdio（デフォルト）、sse、streamable-http をサポートしています。ネットワークトランスポートは、デフォルトで 127.0.0.1 にバインドします。任意の OAuth 保護リソースモードを有効にすると、外部の認可サーバーを使用して、両方の HTTP トランスポートに標準のディスカバリー、JWT ベアラートークンの検証、必須スコープが追加されます。

OAuth 保護リソースの設定に記載されている --auth oauth または PAPER_SEARCH_MCP_AUTH=oauth と、発行者／JWKS／リソース／オーディエンス／スコープの明示的な設定で有効にします。無効または不完全な HTTP 認証設定では、起動に失敗します。stdio は HTTP 認証から独立しています。OAuth を設定していないローカル HTTP は引き続き公開状態のため、そのリスナーを直接公開しないでください。保護されたリモート環境へのデプロイにも、TLS、レート制限、ファイルシステムの分離が必要です。この機能はログインやアカウントをホストするものではなく、外部発行者の OAuth フローに代わるものでもありません。実際の ID プロバイダーとの相互運用性は、デプロイ先で検証する必要があります。

---

機能

• 2 層アーキテクチャ：
  • レイヤー 1（統合ツール群）：複数のソースを同時に検索して重複を除去する高レベルの search_papers と、出版社のオープンアクセスリンクに依存し、順次フォールバックする download_with_fallback を提供します。
  • レイヤー 2（プラットフォームコネクター）：特定の学術プラットフォーム（arXiv、PubMed、bioRxiv など）向けのモジュール式コネクターを提供し、正規表現によるテキスト解析または API フィールドを使って DOI をインテリジェントに抽出します。
• 複数ソースへの対応：arXiv、PubMed、bioRxiv、medRxiv、Google Scholar、IACR ePrint Archive、Semantic Scholar、Crossref、OpenAlex、PubMed Central（PMC）、CORE、Europe PMC、dblp、OpenAIRE、CiteSeerX、DOAJ、BASE、Zenodo、HAL、SSRN、OpenReview、Unpaywall（DOI 検索）、およびオプションの Sci-Hub ワークフローから論文を検索、ダウンロードできます。
• オプトインの高速検索：CLI 検索では、デフォルトで広範なカバレッジを維持します。カバレッジより低レイテンシを重視する場合は、-s fast（OpenAlex、Crossref、arXiv、PubMed、Europe PMC）または -s fastest（OpenAlex、Crossref）を使用してください。
• 標準化された出力：Paper クラスを通じて、一貫した辞書形式で論文を返します。
• 無料優先の設計：オプションの商用または利用制限のある統合機能を使う前に、オープンな公開ソースを優先します。
• オプションの API キーによる強化：Semantic Scholar などのソースは、ユーザーが提供する API キーで機能が向上する場合がありますが、有料利用を強制するものではありません。
• 発見と取得のワークフロー：Google Scholar と Crossref を論文の発見や DOI の補完に利用でき、利用可能な場合はオープンリポジトリや出版社のリンクを使って、合法的に全文を取得します。
• OA 優先のフォールバックチェーン：download_with_fallback は、ソース固有のダウンロード → OpenAIRE／CORE／Europe PMC／PMC での検索 → Unpaywall による DOI 解決 → オプションの Sci-Hub の順に処理します。
• 上限付きの参考文献検索：OpenAlex の参考文献および被引用論文を、DOI または OpenAlex ID から取得できます。明示的な予算と切り捨てメタデータも利用できます。
• MCP 統合：LLM のコンテキスト拡張に対応する MCP クライアントと互換性があります。
• DeepSeek Harness（DSH）統合：各ツールを mcp__paper-search__* として公開する dsh プロファイルバンドル（リポジトリをクローンし、npx @deepseek-ai/[email protected] plugin --profile web add link:./dsh を実行）を提供し、オプションのガイダンススキルも利用できます。
• 拡張しやすい設計：academic_platforms モジュールを拡張することで、新しい学術プラットフォームを簡単に追加できます。

ソース戦略

長期的な目標は、単一の検索エンジンに依存することではなく、明確な役割を持つ複数の無料公開ソースを組み合わせることです。

• オープンなメタデータの基盤：Crossref、OpenAlex、Semantic Scholar、dblp、CiteSeerX、SSRN、Unpaywall（DOI 中心の OA メタデータ）。
• 分野別ソース：arXiv、PubMed、PubMed Central、Europe PMC、IACR。
• オープンアクセスの全文ソース：arXiv、PMC、CORE、OpenAIRE、DOAJ、BASE、Zenodo、HAL、出版社のオープンアクセスリンク。
• 論文の発見と DOI の補完：他の公開メタデータソースが不完全な場合、Google Scholar はタイトル、バージョン、DOI の手がかりを見つけるのに役立ちます。

無料優先の推奨ロードマップ：

1. 現在の公開ソースを安定して維持します。
2. 幅広い無料メタデータソースとして OpenAlex を追加します。
3. 生物医学分野の全文へのアクセスを強化するため、PubMed Central と Europe PMC を追加します。
4. リポジトリベースのオープンアクセス論文の取得に、CORE と OpenAIRE を追加します。
5. Google Scholar は主な正規ソースではなく、主に論文の発見時のフォールバックとして使用します。

プラットフォーム機能マトリクス

このマトリクスには、このリポジトリの機能テストおよびエンドツーエンド回帰テストで得られた実際の連携に関する検証済みの結果が反映されています。各列には、通常の条件下で確認された最も高い機能レベルを示しています。

プラットフォーム	検索	ダウンロード	読み取り	備考
arXiv	✅	✅	✅	オープン API。安定して動作します
PubMed	✅	❌	⚠️ 情報のみ	オープン API。安定して動作します
bioRxiv	✅	✅	✅	オープン API。安定して動作します
medRxiv	✅	✅	✅	オープン API。安定して動作します
Google Scholar	⚠️	❌	❌	上流のボット検出やレート制限により、検索できない場合があります。ソースエラーとして報告されます
IACR	✅	✅	✅	オープン API。安定して動作します
Semantic Scholar	✅	✅ (OA)	✅ (OA)	キーなしで動作します（レート制限あり）。キーを使うと制限が緩和されます。キーが拒否された場合（403）は、キーなしで自動的に再試行します
Crossref	✅	❌	⚠️ 情報のみ	オープン API。安定して動作します
OpenAlex	✅	❌	⚠️ 情報のみ	オープン API。無料の API キーを使うと、1 日あたりの制限が緩和されます
PMC	✅	✅ (OA のみ)	✅ (OA のみ)	OA の PDF のみ。一部のプロキシ環境では、直接ダウンロードがブロックされる場合があります
CORE	✅	✅ (レコードに依存)	✅ (レコードに依存)	無料キーを推奨します。コネクターはバックオフ付きで再試行し、401/403 の場合はキーなしにフォールバックします
Europe PMC	✅	✅ (OA)	✅ (OA)	OA の PDF のみ。一部のプロキシ環境では、直接ダウンロードがブロックされる場合があります
dblp	✅	❌	⚠️ 情報のみ	オープン API。安定して動作します
OpenAIRE	✅	❌	❌	オープン API。一時的な 403 に対し、リクエストプロファイルを段階的に変更しながら 3 回再試行します
CiteSeerX	⚠️	✅ (レコードに依存)	⚠️	API エンドポイントが断続的に利用できないか、ウェブアーカイブにリダイレクトされます
DOAJ	✅	⚠️ (URL に依存)	⚠️ (URL に依存)	PDF の提供状況は論文によって異なります。無料キーを使うとレート制限が緩和されます
BASE	⚠️	✅ (レコードに依存)	✅ (レコードに依存)	OAI-PMH エンドポイントには、機関 IP の登録が必要です。登録がない場合は、エラーにならず空の結果を返します
Zenodo	✅	✅ (レコードに依存)	✅ (レコードに依存)	オープン API。安定して動作します
HAL	✅	✅ (レコードに依存)	✅ (レコードに依存)	オープン API。安定して動作します
SSRN	✅ (OpenAlex のメタデータ)	⚠️ ベストエフォート	⚠️ ベストエフォート	一般公開の検索は検証済みです。SSRN のページと PDF が一致するかは、別途確認する必要があります
OpenReview	✅ (匿名の API v2)	⚠️ 公開のみ	⚠️ 公開のみ	検索は検証済みです。実際の PDF チェックでは、特定のノートの検索で 403 が返されました。PDF の成功はモックテストでのみ確認しています
Unpaywall	✅ (DOI 検索)	❌	❌	PAPER_SEARCH_MCP_UNPAYWALL_EMAIL が必要です
Sci-Hub (オプション)	⚠️ フォールバックのみ	✅	❌	オプションです。ミラーは不安定です。利用者の責任で使用してください
IEEE Xplore 🔑	⚠️ メタデータを設定済み	❌	❌	決定的テストのみ実施済みです。キー認証を使った実環境での検証はありません。メタデータ用のキーでは全文にアクセスできません
ACM DL	✅ (Crossref のメタデータ)	⚠️	⚠️	キーなしで検索できます。ブラウザーのチャレンジにより、PDF の直接取得や読み取りがブロックされる場合があります。OA のフォールバックを使用してください

✅ = 実環境のテストで安定して動作します。 ⚠️ = 動作しますが、上流の不安定さやアクセス制限の影響を受けます。 ❌ = サポートされていません。 🔑 = キーが必要です。 🚧 = 骨組みのみです。

認証情報と API キーの要件

特に記載がない限り、すべてのキーは任意です。~/.config/paper-search-mcp/.env（推奨）またはシェルの環境変数として設定してください。

環境変数	プロバイダー	必須？	入手方法
PAPER_SEARCH_MCP_UNPAYWALL_EMAIL	Unpaywall	はい（設定しないと Unpaywall は無効）	有効なメールアドレスを用意し、unpaywall.org で登録してください
PAPER_SEARCH_MCP_CORE_API_KEY	CORE	推奨	core.ac.uk/services/api で無料で取得できます
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar	任意	semanticscholar.org で無料で取得できます。レート制限が緩和されます
PAPER_SEARCH_MCP_OPENALEX_API_KEY	OpenAlex	任意	openalex.org/settings/api で無料で取得できます。キーなしの場合の日次上限が 10 倍になります
PAPER_SEARCH_MCP_OPENALEX_EMAIL	OpenAlex	任意	OpenAlex の User-Agent に使用する連絡先メールアドレス
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL	Google Scholar	任意	HTTP/HTTPS プロキシの URL。アクセスが保証されるわけではなく、プロバイダーの制限も解除されません
PAPER_SEARCH_MCP_DOAJ_API_KEY	DOAJ	任意	doaj.org で無料で取得できます。時間あたりのレート制限が緩和されます
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN	Zenodo	任意	zenodo.org で無料で取得できます。非公開レコードには必須です
PAPER_SEARCH_MCP_IEEE_API_KEY	IEEE Xplore	有効化に必須	developer.ieee.org で無料で取得できます

すべての変数は PAPER_SEARCH_MCP_<NAME> のプレフィックス形式に従います。後方互換性のため、プレフィックスのない旧形式の名前（例：CORE_API_KEY、UNPAYWALL_EMAIL）も引き続きサポートされています。

---

既知の上流プロバイダーの制限事項

一部の検索失敗は、このプロジェクトのバグではなく、外部プロバイダーの不安定さが原因です。

ソース	症状	原因	回避策
Google Scholar	HTTP／ネットワークエラー、CAPTCHA、または同意ページが繰り返し表示される場合のソースエラー	上流プロバイダーのレート制限、アクセスチェック、または接続の問題	リクエスト頻度を下げるか、別の公開ソースを使用します。CAPTCHAは自動では解決されません
Semantic Scholar	429レート制限レスポンス	匿名アクセスのレート制限	PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY を設定します。キーが拒否された場合（403）、コネクターはキーなしで自動的に再試行します
OpenAlex	403／429または日次クォータエラー	匿名アクセスの日次制限	PAPER_SEARCH_MCP_OPENALEX_API_KEY を設定します
CORE	500／タイムアウトエラー	認証なしのレート制限	PAPER_SEARCH_MCP_CORE_API_KEY を設定します（無料）。コネクターは指数バックオフで再試行し、401／403の場合はキーなしにフォールバックします
OpenAIRE	一時的な403レスポンス	IPベースのセッションレート制限	コネクターはプロファイルごとに3回再試行し、プレーンなセッション → XML Acceptヘッダー → Mozilla UAを指定した生の requests.get の順に試します
CiteSeerX	ウェブアーカイブへのリダイレクトによる404	PSUエンドポイントが断続的にアーカイブへリダイレクトする	回避策はありません。コネクターは適切に空の結果を返します
BASE	検索結果が0件	OAI-PMHエンドポイントには機関IPの登録が必要	APIアクセスには base-search.net で登録します。登録しない場合、コネクターは適切に空の結果を返します
SSRNの全文	HTTP 403またはIDを取得できない	公開ページ／PDFの配信が制限されている場合がある	検索にはOpenAlexを使用します。ダウンロードでは、ログインなし、リダイレクト、またはHTML検索へのフォールバックで失敗が報告されます
PMC／Europe PMC	PDFダウンロード時のProxyError	ローカルプロキシがHTTPSによるPDFの直接ダウンロードをブロックしている	プロキシを無効にするか、代わりに download_with_fallback を使用します
Unpaywall	完全にスキップされる	UNPAYWALL_EMAIL 環境変数が設定されていない	~/.config/paper-search-mcp/.env で PAPER_SEARCH_MCP_UNPAYWALL_EMAIL を設定します

Google Scholarの失敗は、統合MCPおよびCLI検索では errors.google_scholar に記録されます。他のソースで検索に成功した場合は、引き続き論文が返されます。Scholarを直接検索した場合、これらの失敗に対して GoogleScholarSearchError が発生します。通常の空の検索結果ページでは、空のリストが返されます。後続ページで失敗した場合、ソースは失敗として報告され、それ以前のページが揃った結果として返されることはありません。タイムアウトも、論文が存在しないことを意味するのではなく、ソースエラーとして発生します。HTTP 403／429／503の再試行を使い切った場合、またはCAPTCHAが発生した場合、共有Scholarコネクターは60秒間のクールダウンに入ります。ブロックが連続すると、クールダウンは最大15分まで指数的に延長されます。有効な上流の Retry-After がある場合は、この期間がさらに延長されることがあります。ページの取得に成功すると、連続回数はリセットされます。クールダウン中の呼び出しは、再試行までの時間を示して直ちに失敗し、Scholarには接続しません。再試行では、24時間以内の有効な Retry-After の秒数またはHTTP日付に従います。それより長い待機指示がある場合、プロバイダーの指定より早く再試行することなく、このコネクターが存続する間は自動リクエストを一時停止します。30秒を超える遅延は、ワーカーをスリープさせずに後続の呼び出しへ引き継がれます。同時に行われる呼び出しは、同じペース調整済みセッションを共有します。コネクターはリクエストごとにIDを切り替えたり、CAPTCHAを解決したりしません。クールダウンの状態はプロセス内に限られ、上流プロバイダーのクォータや、その期間が過ぎた後の復旧を保証するものではありません。

サーベイでは、たとえばMCPの search_papers(query, sources="google_scholar,openalex,semantic,crossref") またはCLIの paper-search search "query" -s google_scholar,openalex,semantic,crossref のように、別のソースを明示的に選択してください。Scholarがクールダウン中でも、検索に成功したプロバイダーは、それぞれのソースラベルと論文を返します。代替ソースにはそれぞれ独自のアクセス制限／レート制限があります。代替ソースがGoogle Scholarの検索結果として暗黙に返されることはありません。

ローカル PDF セクション抽出

extract_sections は、すでにダウンロード済みの PDF を認識された独立した見出しで分割し、抽出したテキストの順序とページ範囲を維持しながら、明示的な上限と切り詰めを適用します。読み取りは設定済みのダウンロードルート内に限定されます。ネットワーク通信、OCR、医療に関する推論、新たな依存関係は追加されません。ラベルはヒューリスティックに基づくため、不確かな場合があります。アクセスルール、CLI の使い方、パーサーの制限については、制限付き PDF セクションを参照してください。

arXiv PDF のダウンロードと読み取り

arXiv のダウンロードでは、現行形式および旧形式の論文 ID のみを検証し、リクエストを直列化して送信間隔を調整し、HTTP ステータスを確認します。また、同じディレクトリ内の一時ファイルに最大 100 MiB までストリーミングし、PDF ヘッダーとパーサーを確認したうえで、保存先をアトミックに置き換えます。転送に失敗した場合や PDF が無効な場合、既存ファイルは変更されません。ダウンロードでは接続タイムアウトに 10 秒、読み取りタイムアウトに 30 秒を設定しますが、転送やパーサー実行時間の合計に対する厳密な上限はなく、拒否されたレスポンスを自動的に再試行することもありません。read arxiv は、無効な PDF、暗号化された PDF、画像のみの PDF を、正常な空の出力ではなくエラーとして報告します。OCR は実行せず、無効なキャッシュファイルも削除しません。

オプションの有料プラットフォームコネクター（フェーズ 3）

IEEE Xplore はオプトイン方式のメタデータ検索を提供します。既存の API キーが設定されるまで無効です。ACM Digital Library の検索はキー不要でデフォルトで有効になっており、ACM の DOI プレフィックス 10.1145 に限定した Crossref メタデータを使用します。

プラットフォーム	環境変数	状態
IEEE Xplore	PAPER_SEARCH_MCP_IEEE_API_KEY	ページネーション対応のメタデータ検索。直接のダウンロードと読み取りには未対応
ACM Digital Library	なし	Crossref を利用した検索。PDF のダウンロードと読み取りは出版社のアクセス条件によります

有効にする方法：

export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key>       # free key at https://developer.ieee.org/

IEEE のキーを設定すると、起動時に ieee とそのツールが登録されます。IEEE のメタデータに関する制限と全文取得の境界を参照してください。ACM（acm、search_acm、download_acm、read_acm_paper）は常に利用できます。従来の PAPER_SEARCH_MCP_ACM_API_KEY / ACM_API_KEY 設定は使用されなくなったため、削除できます。

ACM のダウンロードには 10.1145/... のような ACM DOI が必要です。出版社のブラウザーチャレンジにより、スクリプトからのアクセスがブロックされる場合があります。オープンリポジトリを試すには、download_with_fallback(source="acm", paper_id="10.1145/...", doi="10.1145/...") を使用してください。read_acm_paper はテキストを抽出する前に PDF を save_path にダウンロードし、そのファイルを上書きする場合があります。

無料ソースの拡充（フェーズ 4）

追加の公開ソースコネクターが MCP サーバーに統合されています。

• zenodo：公式 Zenodo REST API コネクター（検索、レコードに応じた PDF のダウンロードと読み取りに対応）。
• hal：HAL 公開 API コネクター（検索、レコードに応じた PDF のダウンロードと読み取りに対応）。
• ssrn：OpenAlex を利用した発見に対応し、SSRN の ID を厳格に照合したうえで、公開ダウンロードを可能な範囲で検証します。
• openreview：匿名の公開 API v2 論文に対応し、レビューと非公開メモは除外します。OpenReview がホストする PDF のダウンロードと読み取りを検証します。
• unpaywall：単独検索（search_unpaywall）とフォールバック URL の解決に対応する、DOI 中心の OA メタデータソースです。

SSRN の統合では、コンプライアンスを最優先しています。SSRN のページで公開されている PDF の直接リンクのみを試します。ログインやアクセス制限付きの配信が必要な場合、コネクターはアクセス制御を回避せず、その旨を明確に伝えます。

Sci-Hub に関する注意

Sci-Hub のサポートは、明示的に有効化することを選んだユーザー向けのオプションコネクターとして利用可能な状態にできますが、デフォルトまたは推奨される全文取得手段として扱うべきではありません。

• download_with_fallback では、Sci-Hub はデフォルトで無効です。使用を明示的に選ぶ場合に限り、use_scihub=true を渡してください。
• 利用可能性は不安定で、ミラーは頻繁に変更されます。
• 法的リスクやポリシー上のリスクは、管轄地域によって異なります。
• README とツールの説明では、有効化および使用の責任がユーザーにあることを明確に示してください。
• 可能な場合は、オープンアクセスソースと出版社が許可するソースを常に先に試してください。

---

インストール

ワークフローに最適な方法を選択してください。すべての方法で、同じオプションの API キーを使用できます。

---

Claude Code（スキル）— Claude Code ユーザーにおすすめ

MCP サーバーではなく、Claude Code のスキルとしてインストールします。これにより、論文や学術文献などを探すよう依頼すると、Claude が自動的に論文検索を利用できます。MCP の設定は不要です。

前提条件：uv と Claude Code。

手順 1 — CLI をインストール：

uv tool install paper-search-mcp

手順 2 — スキルをインストール：

mkdir -p ~/.claude/skills/paper-search
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/claude-code/SKILL.md \
  -o ~/.claude/skills/paper-search/SKILL.md

手順 3（任意）— API キーを設定：

任意の API キーを設定するには、~/.config/paper-search-mcp/.env を作成してください（環境変数を参照）。

これで完了です。 次回 Claude Code を起動したときに、論文を探すよう依頼するだけで、スキルが自動的に有効になります。たとえば、次のように依頼できます。

• 「CRISPR の塩基編集に関する最近の論文を探して」
• 「arxiv と semantic scholar で、トランスフォーマーのアテンション機構を検索して」
• 「arxiv の論文 2106.12345 の PDF をダウンロードして」

このスキルは、MCP サーバーと同じライブラリをラップする CLI（paper-search）を使用します。検索とダウンロードでは JSON を、読み取りではプレーンテキストを出力します。

paper-search download が status: "ok" を返すのは、返されたパスが読み取り可能な空でない通常ファイルで、PDF ヘッダーが含まれている場合のみです。コネクターのエラー文字列、ファイルの欠落、保存された HTML エラーページの場合は、JSON エラーが返され、終了コードは 1 になります。この簡易チェックでは、PDF が完全であることや論文の同一性は確認されません。これらの確認は引き続き、ソースコネクターと読み手が行う必要があります。

レイテンシーが重要な場合は、検索ソースを明示的に選択してください。

paper-search search "gender imbalance neuroscience references" -s fast -n 3
paper-search search "gender imbalance neuroscience references" -s fastest -n 3
paper-search search "gender imbalance neuroscience references" -s all -n 3
paper-search download semantic DOI:10.1038/s41593-020-0658-y -o ./downloads

CLI では、デフォルトの広範なソースセットとして -s all が引き続き使用されます。--exhaustive は互換性のために受け付けられますが、広範な検索がすでにデフォルトであるため、何も行いません。明示的な -s の選択は常に優先され、-s fast と -s fastest も同様です。広範なプリセットには、サポートされている公開ソースが含まれます。オプションの有料ソースがこれらのプリセットに追加されることはありません。

-s fast は OpenAlex、Crossref、arXiv、PubMed、Europe PMC を選択します。空白以外の値が設定された PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY（または旧形式の SEMANTIC_SCHOLAR_API_KEY）がある場合は、Semantic Scholar も含まれます。-s fastest が選択するのは OpenAlex と Crossref のみです。プリセットはレイテンシーを重視した選択肢であり、応答時間や網羅的な文献カバレッジを保証するものではありません。匿名での Semantic Scholar リクエストが 429 を返した場合は、直ちに失敗します。認証済みのリクエストでは、上限付きの再試行が引き続き行われます。

選択された検索ソースのみが構築されます。ソースのリストとプリセットは厳密に尊重され、クエリに DOI が含まれていても、別のソースが追加されることはありません。DOI を検索するには -s unpaywall を使用するか、カンマ区切りのソースリストに unpaywall を明示的に含めてください。広範な all プリセットには、すでにこれが含まれています。MCP サーバーの検索時のデフォルトは変更されません。

遅いソースによって CLI 検索が滞るのを防ぐには、ソースごとの期限を有効にしてください。

paper-search search "robot scientist" -s fast --source-timeout 45

--source-timeout SECONDS には、正の有限値を指定する必要があります。選択されたソースは、それぞれ別の Python プロセスで実行され、同時実行数は最大 4 つです。各ソースの制限時間は、OS のプロセス作成が完了した後に開始し、Python／プロバイダーの初期化、検索、シリアライズ、ワーカーの終了までを含みます。プロセスの作成、ワーカーの空きを待つ時間、プロセスのクリーンアップにかかる時間は、この制限時間の対象外です。コマンド全体に対する期限ではありません。タイムアウトしたワーカーは、スロットが再利用される前に強制終了され、終了処理が行われます。そのため、ブロックされたネットワーク呼び出しによって Python のスレッドエグゼキューターの終了処理が滞ることはありません。成功したソースの結果は保持され、タイムアウトしたソースは errors に表示され、source_results の件数は 0 になります。ソースの選択、ラベル、並べ替え、JSON フィールド、部分的な結果を返す際の終了ステータス（0）に変更はありません。サブプロセスの起動により、特に制限時間を非常に短くした場合はオーバーヘッドが増えます。このフラグを指定しない場合、既存のコネクター固有のタイムアウトとプロセス内検索がそのまま使用されます。

検索結果を引用数または公開日で並べ替えます。

paper-search search "transformer attention" --sources arxiv,semantic --sort citations
paper-search search "CRISPR" --sort date

--sort relevance（デフォルト）では、既存の順序が維持されます。選択したソースの順序が保たれ、各ソースが返す結果の順序も変わりません。ソース間の関連度スコアは計算されません。--sort citations は引用数の多い順に、--sort date は公開日が新しい順に並べ替えます。並べ替えは重複排除後にクライアント側で行われ、取得済みの結果のみが対象です（--max-results はソースごとに適用されます）。ソースへのクエリは変更されず、ソース全体から最も引用数の多い論文や最新の論文を検索することもありません。同順位の場合は元の順序が維持されます。値がない場合や無効な値は最後に並びます。数値形式の引用数文字列にも対応しています。日付には ISO 形式の日付／タイムスタンプを指定できます。タイムゾーン情報のないタイムスタンプと日付のみの値は UTC として扱われます。デフォルトの JSON 出力と選択されたソースは変更されません。

CLI からの MCP ツール

paper-search tool は、ソース固有のオプションや DOI 検索を含め、MCP サーバーと同じ登録済みツールを呼び出します。必須の引数は位置引数で指定し、オプションの引数はケバブケースのフラグを使用します。ブール値のフラグには --flag と --no-flag を使用します。省略したオプションには MCP のデフォルト値が適用されます。

paper-search tool --help
paper-search tool --list  # JSON tool list, schemas, and annotations
paper-search tool search_crossref --help
paper-search tool search_crossref "transformer attention" --filter from-pub-date:2024-01-01 --sort published --order desc --max-results 2
paper-search tool get_crossref_paper_by_doi 10.1038/nature12373
paper-search tool search_iacr "cryptography" --no-fetch-details

オブジェクトとリストは JSON を返し、テキストとダウンロードパスはプレーンテキストを返します。例外が発生した場合は JSON エラーを返し、終了コード 1 で終了します。無効な CLI 構文の場合は終了コード 2 で終了します。通常の MCP 結果では、ツール自体が返すエラーや部分的な結果のフィールドを含め、元の意味が維持されます。--list に表示されるのは現在の設定で有効になっているツールのみです。そのため、IEEE ツールには引き続き API キーが必要です。既存の search、download、read、sources コマンドに変更はありません。ツール呼び出しでは、MCP ツールのソース選択とタイムアウトの動作が維持されます。Sci-Hub へのフォールバックは、--use-scihub を指定した場合のみ有効になります。

スキルの ZIP アップロードとその他の Claude ランタイム

上記の手順では、Claude Code スキルの構成に従って、ローカルの Claude Code スキルを ~/.claude/skills/paper-search/SKILL.md にインストールします。ZIP のアップロードは必要ありません。

GitHub の Download ZIP にはリポジトリ全体が含まれており、スキルは paper-search-mcp-main/claude-code/ の下に格納されています。これは単体のスキルアーカイブではありません。アップローダーで SKILL.md の階層が深すぎると表示された場合は、まずアーカイブの構成を確認してください。Anthropic のカスタムスキルのパッケージ化ガイドでは、アーカイブのルートにスキルフォルダーを 1 つ配置し、その中にスキルファイルを直接置くことが指定されています。

paper-search-skill.zip
└── paper-search/
    └── SKILL.md

この構成を確認または調整するために作成するには、リポジトリのチェックアウト先で次のコマンドを実行します（Python 3 が必要です。paper-search-skill.zip は上書きされます）。

from zipfile import ZIP_DEFLATED, ZipFile

with ZipFile("paper-search-skill.zip", "w", compression=ZIP_DEFLATED) as archive:
    archive.write("claude-code/SKILL.md", arcname="paper-search/SKILL.md")

再利用可能なビルダーも用意されています：python scripts/build_skill_zip.py --output paper-search-skill.zip。--force を指定しない限り、既存ファイルの上書きは拒否されます。アーカイブの構成、フロントマター、バイト単位で同一の指示内容は、オフラインテストで検証されています。

これは指示のみをパッケージ化するもので、Python の依存関係を同梱したり、paper-search をインストールしたり、MCP 接続を設定したりするものではありません。同梱されたスキルは、CLI を実行でき、学術サービスにアクセスできるランタイムを必要とします。Claude web やその他のランタイムでのアップロードの受け入れと実行は、このプロジェクトでは検証されていません。スキルを調整する前に、そのランタイムで現在求められているメタデータ、パッケージのインストール、ネットワークアクセス、コード実行の要件を確認してください。代わりに MCP クライアントを使用する場合は、以下の MCP インストール方法に従ってください。スキル ZIP をアップロードしても、外部 MCP サーバーが起動したり接続されたりすることはありません。

---

MCP サーバー設定ファイルの場所（以下の方法で使用）

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

---

方法 1 — Smithery（ワンコマンド、Claude Desktop におすすめ）

npx -y @smithery/cli install @openags/paper-search-mcp --client claude

Smithery が正しい設定ブロックを自動的に書き込みます。JSON を手動で編集する必要はありません。

---

方法 2 — uvx（インストール不要、常に最新版）

uvx は、永続的にインストールすることなく、PyPI からパッケージを直接実行します。uv が必要です。

# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

⚠️ macOS に関する注意：uvx が生成するラッパースクリプトは realpath に依存していますが、macOS には標準で含まれていません。realpath: command not found エラーが表示される場合は、GNU coreutils（brew install coreutils）をインストールするか、代わりに 方法 3（uv run） を使用してください。こちらにはこの制限はありません。

Claude Desktop の設定：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uvx",
      "args": ["paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
      }
    }
  }
}

---

方法 3 — uv（永続インストール）

uv tool install paper-search-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": ["tool", "run", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
      }
    }
  }
}

---

方法 4 — pip（標準的な Python インストール）

pip install paper-search-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "python",
      "args": ["-m", "paper_search_mcp.server"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
      }
    }
  }
}

python が PATH にない場合は、フルパス（例：/usr/bin/python3 または C:\Python311\python.exe）に置き換えてください。which python3／where python を実行すると、場所を確認できます。

---

方法 5 — npx（Smithery CLI 経由、ローカルに Python は不要）

npx -y @smithery/cli run @openags/paper-search-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@openags/paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": ""
      }
    }
  }
}

---

方法 6 — Docker

docker build -t paper-search-mcp .
docker run --rm -i \
  -e [email protected] \
  -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  paper-search-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
      }
    }
  }
}

---

方法 7 — クローンしてソースから実行（開発用／macOS でのローカル利用に推奨）

macOS では、これが最も信頼性の高い方法です。ラッパースクリプトも realpath の問題もありません。

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repo
git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp

# 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
uv run -m paper_search_mcp.server

Claude Desktop の設定（ディレクトリのパスを実際にクローンした場所に置き換えてください）：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/paper-search-mcp",
        "-m", "paper_search_mcp.server"
      ],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
      }
    }
  }
}

たとえば、/Users/mac/Pengsong/paper-search-mcp にクローンした場合：

"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]

初回実行時、uv run は依存関係を分離された環境に自動的にインストールするため、pip install や venv は不要です。

クライアントごとに stdio プロセスを起動する代わりに、共有ネットワークサーバーを 1 つ起動するには：

paper-search-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

利用可能なトランスポートは stdio、sse、streamable-http です。デフォルトは引き続き stdio です。同じネットワーク設定は、 PAPER_SEARCH_MCP_TRANSPORT、PAPER_SEARCH_MCP_HOST、 PAPER_SEARCH_MCP_PORT、PAPER_SEARCH_MCP_PATH でも指定できます。コマンドラインオプションが 優先されます。デフォルトの --auth none を使用している場合、0.0.0.0 のようなループバック以外のホストにバインドすると、 認証されていないサーバーが外部に公開されます。保護された HTTP を利用するには、 オプションの OAuth モード を設定し、バックエンドを TLS および適切なデプロイ制御の背後に配置してください。それ以外の場合は、認証済みゲートウェイを使用してください。

開発を継続する場合は、編集可能なコピーを任意でインストールできます。

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

---

DeepSeek Harness（DSH）

論文検索はDeepSeek Harness（dsh）内でプロファイルバンドルとして利用できます。このバンドルは MCP サーバーを起動し、任意の dsh プロファイルにすべてのツールを mcp__paper-search__* として登録します。バンドルがマウントするのは構成行のみです。MCP サーバー自体には変更を加えません。

前提条件：uv（デフォルトのランチャーは uvx）と pnpm（dsh plugin は pnpm に処理を渡します）が必要です。以下のコマンドでは npx @deepseek-ai/dsh ランチャーを使用しています（グローバルインストールは不要です）。dsh をグローバルインストールしている場合は、プレフィックスを省略してください。

git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp
npx @deepseek-ai/[email protected] plugin --profile web add link:./dsh

link: はチェックアウトからバンドルの設定を更新します。git pull では、別途起動する PyPI サーバーは更新されません。ソースチェックアウトから起動する方法と、再現可能なバージョン選択については dsh/README.md を参照してください。web をプロファイル名に置き換えてください。存在しないプロファイルは自動的に初期化されます。プロファイルを再起動する（npx @deepseek-ai/[email protected] web を実行するか、再度起動する）と、mcp__paper-search__search_papers、mcp__paper-search__download_with_fallback、mcp__paper-search__search_arxiv などのツールが表示されます。

API キー：環境変数の手順に従ってください。サーバーは ~/.config/paper-search-mcp/.env を自動的に読み込みます。DSH は、起動したプロセスから認証情報と思われる環境変数を意図的に削除するため、シェルでエクスポートした変数はサーバーに渡されません。変数を明示的に渡すには、~/.dsh/profiles/<name>/cordis.patch.yml の mcp-paper-search 行をオーバーライドしてください（設定のオーバーライドではオブジェクト全体が置き換えられます。詳しい例は dsh/README.md を参照してください）。

オプションのスキル（ワークフロー、ソース表、ツールの対応付けに関する使用ガイダンス）：

mkdir -p ~/.dsh/skills && cp -r dsh/skills/paper-search ~/.dsh/skills/

アンインストール：

npx @deepseek-ai/[email protected] plugin --profile web remove paper-search-mcp-dsh
rm -rf ~/.dsh/skills/paper-search

バンドルを削除すると、構成からその行が取り除かれます。ダウンロード済みの論文、パッケージキャッシュ、ユーザー管理の設定は削除されません。

すでに独自の @deepseek-ai/dsh-mcp-client 行を使って paper-search-mcp を実行している場合は、バンドルを追加する前にその行を削除するか、どちらか一方に異なる serverName を指定してください。serverName が重複していると、読み込みに失敗します。バンドルのパッケージバージョンは、このチェックアウトの Python プロジェクトバージョンに対応しています。代替ランチャー（uv tool run、python -m、npx）、環境変数の転送、開発については dsh/README.md に記載されています。

---

環境変数（.env ファイル）

JSON 設定にキーを直接記述する代わりに、ユーザー設定ファイルに保存できます（起動時に自動的に読み込まれます）。

mkdir -p ~/.config/paper-search-mcp
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/.env.example \
  -o ~/.config/paper-search-mcp/.env
$EDITOR ~/.config/paper-search-mcp/.env

[email protected]
PAPER_SEARCH_MCP_CORE_API_KEY=
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN=
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL=
PAPER_SEARCH_MCP_IEEE_API_KEY=

カスタムパスを使用するには、export PAPER_SEARCH_MCP_ENV_FILE=/absolute/path/to/.env を設定します。

PAPER_SEARCH_MCP_ プレフィックスのない従来の変数名（例：CORE_API_KEY、UNPAYWALL_EMAIL）も、後方互換性のため引き続きサポートされています。

---

オプションのローカル検索キャッシュ

オプトイン方式の SQLite 検索キャッシュでは、TTL、サイズ制限、ステータス確認、キャッシュの消去を利用できます。デフォルトでは無効で、認証が必要なソースには適用されません。

貢献

皆さまからの貢献を歓迎します！始め方は以下のとおりです。

1. リポジトリをフォークする： GitHub で「Fork」をクリックします。

2. クローンしてセットアップする：

   git clone https://github.com/yourusername/paper-search-mcp.git
   cd paper-search-mcp
   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"
   

3. 変更を加える：

   • academic_platforms/ に新しいプラットフォームを追加します。
   • tests/ のテストを更新します。

4. プルリクエストを送信する： 変更をプッシュし、GitHub で PR を作成します。

---

デモ

TODO

対応予定の学術プラットフォーム

• [√] arXiv
• [√] PubMed
• [√] bioRxiv
• [√] medRxiv
• [√] Google Scholar
• [√] IACR ePrint Archive
• [√] Semantic Scholar
• [√] Crossref
• [√] PubMed Central（PMC）
• [√] CORE
• [√] Europe PMC
• [√] Sci-Hub の警告と有効化に関するドキュメント

開発タスク

• [√] 非同期検索のバグを修正し、MCP イベントの高速かつ安定した動作を確保
• [√] エンドツーエンドの完全なパイプラインテストスクリプト（検索、解析、ダウンロード）
• [√] 2 層のフェデレーションアーキテクチャを確立（レイヤー 1 ツール：search_papers）
• [√] メタデータフィールド全体および抄録へのフォールバックで DOI 抽出を確実に実行
• 引用グラフと論文関係のコンテキスト機能
• [√] OpenAlex プロバイダーのフルスタック対応を拡張

優先度の高い無料およびオープンソースの情報源

• [√] PubMed Central (PMC)
• [√] CORE
• [√] OpenAlex
• [√] Europe PMC
• [√] OpenAIRE
• [√] dblp
• [√] CiteSeerX
• [√] DOAJ
• [√] BASE
• [√] Zenodo
• [√] HAL
• [√] SSRN（文献の発見と、可能な範囲での全文取得）
• [√] Unpaywall（単独の DOI 検索ソース）

オプションおよびコア対象外の連携

• ResearchGate
• JSTOR
• ScienceDirect
• Springer Link
• [√] IEEE Xplore（オプションのスケルトン — IEEE_API_KEY で有効化）
• [√] ACM Digital Library（キー不要の Crossref 検索。出版社の PDF へのアクセス可否は異なります）
• Web of Science
• Scopus

---

スター履歴

---

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳しくは LICENSE ファイルをご覧ください。

---

paper-search-mcp で充実した研究を！問題が発生した場合は、GitHub issue を作成してください。

機関向けメタデータコネクターを明示的に指定する

Web of Science Starter は、search_wos または明示的な wos ソース（paper-search search 'TI=(machine learning)' -s wos）でのみ利用できます。キーを指定しても、デフォルト、all、fast、または fastest の検索に追加されることはありません。実行時に PAPER_SEARCH_MCP_WOS_API_KEY（従来の WOS_API_KEY も使用可能）を指定してください。このコネクターはアカウントを作成せず、認証情報を永続化しません。制限、エラー、機能の境界、および検証状況については、機関向けコネクターガイドをご覧ください。

Scopus も同様に明示的な指定でのみ利用でき（-s scopus または MCP の search_scopus）、PAPER_SEARCH_MCP_SCOPUS_API_KEY（従来の SCOPUS_API_KEY）を使用します。メタデータ検索のデフォルトは STANDARD です。抄録は paper-search read scopus ID または MCP の read_scopus_paper で取得できます。ScienceDirect の記事を取得するには、明示的に --full-text / full_text=true を指定し、DOI/PII の一致を確認する必要があります。応答では full_text、abstract_only、unavailable がそれぞれ別々に示されます。これらのフィクスチャテストでは、どちらのコネクターも機関契約に基づく実際の利用権限は検証されていません。