arxiv-mcp-server

---

概要

arXiv API とその OAI-PMH メタデータフィードから、arXiv 論文、メタデータ、全文を取得できます。クエリ、カテゴリ、投稿日時で論文を検索し、ID を指定して構造化メタデータを取得できます。また、HTML と PDF の表示形式を順次試す自動フォールバック機能を使って、論文の全文を読み取れます。stdio プロセス、ローカルの Streamable HTTP サーバー、または上記の公開ホスト型エンドポイントとして動作します。

ツール

ツール	説明
arxiv_search_papers	フィールドプレフィックス、カテゴリ、日付のフィルターを指定して、クエリで arXiv 論文を検索します
arxiv_get_metadata	1 件以上の論文について、arXiv ID を指定してメタデータを取得します
arxiv_read_paper	HTML、ar5iv、または PDF から抽出した内容をフォールバックとして使い、論文の全文を読み取ります
arxiv_list_categories	arXiv のカテゴリ体系を一覧表示します。グループによる絞り込みも可能です

リソース

リソース	説明
arxiv://paper/{paperId}	arXiv ID による論文のメタデータ
arxiv://categories	arXiv のカテゴリ体系全体

機能リファレンス

arxiv_search_papers _ツール

• クエリでは、フィールドプレフィックス ti:、au:、abs:、cat:、co:、jr:、all: と AND／OR／ANDNOT を使用でき、最大1000文字です。category にはコード（cs.CL）またはアーカイブ全体（astro-ph、cs、math）を指定します
• クエリの文法はarXivに準拠しています。スペースで区切った語句は OR で結合されます（すべての語句を必須にするには AND を記述します）。演算子は大文字のみ使用でき、3種類の演算子はすべて同じ優先順位で右からグループ化されます（a AND b OR c は a AND (b OR c) です）。複数語からなるトピックは引用符で囲み（"graph neural networks" AND cat:cs.LG）、フィルターの前に候補を括弧で囲みます。arXivは引用符で囲んだ句の外にある of や the などの一般的な単語を無視します
• sort_by（relevance／submitted／updated）と sort_order で並べ替えます。submitted_from／submitted_to は、両端を含むUTCの YYYY-MM-DD の範囲です。1回の呼び出しで最大50件の結果を取得でき、max_results をそれより大きく指定しても50件が返されます
• arXivがクエリに対して返すのは最初の10,000件のみです。start に10,000を指定すると start_beyond_result_limit で失敗します。さらに結果を取得するには日付範囲を使用してください
• 出力には、実際に適用されたクエリ、合致した総件数、ページオフセットが含まれます。結果が空のページには、エラーの代わりに復旧方法が示されます。ローカルミラーで総件数が50,000件に達した場合、その件数が下限値であることを示す totalFoundIsLowerBound: true が含まれます

---

arxiv_get_metadata _ツール

• 最大100件のIDを受け取り、最初の10件を検索します。残りは remaining_ids に返されるので、次の呼び出しの paper_ids に指定します
• バージョン付き（2401.12345v2）、バージョンなし、2007年より前のID（hep-th/9901001）を受け付けます。arXiv: プレフィックス、またはarxiv.orgの abs／pdf／html URLも任意で指定できます
• 見つかった論文に加え、残りのIDについて型付きの not_found[]（not_in_arxiv／version_not_in_mirror／version_not_served／live_lookup_failed／invalid_id）を返します。version_not_served は、arXivのAPIがHTTP 500を返す、置き換え済みの2007年より前のバージョンを示し、その detail には最新バージョンが記載されます。ローカルミラーを使用している場合、live_lookup_failed はミラーに存在せず、ライブ検索にも失敗したIDを示します。ミラーから取得できた論文は引き続き返されます
• 適切な形式のIDがない場合は invalid_id、すべてのIDが見つからない場合は no_match、ライブAPIでしか取得できないバージョンの場合は version_unavailable、arXivが提供しないバージョンをIDがすべて指定している場合は version_not_served で失敗します

---

arxiv_read_paper _ツール

• arXiv HTML、次にar5iv、最後にPDFのテキスト抽出を試します。どの方法で取得したかは source フィールドに示されます。PDFのテキストはプレーンテキストのため、数式、表、見出しは平坦化されます
• ar5ivは論文ごとに1つのレンダリングのみ保持するため、ar5ivの本文は paper_id とは別の改訂版である場合があり、その場合は revision_unconfirmed: true が付与されます。ただし、バージョンを指定せずに読み込み、arXivのAPIで論文のバージョンがv1のみと報告された場合を除きます。pdf_url は paper_id で指定された改訂版と正確に一致します
• max_characters のデフォルトは100,000です（論文全体を取得するには null を指定します）。start を使ってページ分割します。最初のページには、セクション見出しとオフセットを示す outline が含まれます
• paper_id は arxiv_get_metadata と同じ表記のIDを受け付けます
• invalid_id、content_unavailable（レンダリングもPDFもない場合）、pdf_extraction_failed（PDFにテキストレイヤーがない、または解析できない場合）、version_unavailable（バージョンを指定したIDでライブAPIが必要な場合）、または version_not_served（arXivが提供しない置き換え済みの2007年より前のバージョン。最新バージョンと、このバージョンのPDFが示されます）で失敗します

---

arxiv_list_categories _ツール

• 8つの最上位グループ（cs、econ、eess、math、physics、q-bio、q-fin、stat）にまたがる約155のカテゴリー
• 任意の group フィルターで結果を絞り込めます
• 静的データのため、常に成功します

---

arxiv://paper/{paperId} _リソース

• paperId は arxiv_get_metadata と同じ表記のIDを受け付けます。旧形式のIDのスラッシュはパーセントエンコードしてください（arxiv://paper/hep-th%2F9901001）
• empty_id、invalid_id、no_match、version_unavailable、または version_not_served で失敗します

---

arxiv://categories _リソース

• { categories: [...] } を返します。各エントリには code / name / group が含まれるフラットな配列です
• パラメーターはありません。24時間キャッシュ可能です

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、および任意で OpenTelemetry トレースを利用できる構造化ロギングに対応しています。

arXiv 固有の機能：

• 読み取り専用で、認証は不要です
• arXiv の3秒間のクロール遅延を守るリクエストキューを備えています。レート制限の応答は、クールダウンとともに即座に失敗します
• 論文のテキストは、arXiv HTML、ar5iv、PDF 抽出の順にフォールバックします
• arXiv のカテゴリ分類体系全体を静的データとして埋め込んでいます
• 検索とメタデータに対するレート制限の影響をなくす、任意のローカル OAI-PMH メタデータミラー（SQLite + FTS5）を利用できます。任意：ローカルミラーを参照してください

エージェント向けの出力：

• arxiv_read_paper は source の名前を示し、arxiv_search_papers は実際に使用されたクエリを返します
• arxiv_get_metadata は、見つかった論文と、見つからなかった各項目の理由を示す型付きの not_found[] を返します
• 型付きの source および not_found[].reason 列挙型により、呼び出し側はデータに応じて処理を分岐できます

はじめに

公開ホストインスタンス

https://arxiv.caseyjhand.com/mcp に公開インスタンスがあります。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントから接続できます：

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "streamable-http",
      "url": "https://arxiv.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

または npx を使用します（Bun は不要です）：

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

または Docker を使用します：

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/arxiv-mcp-server:latest"]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。

インストール

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

git clone https://github.com/cyanheads/arxiv-mcp-server.git

2. ディレクトリに移動します：

cd arxiv-mcp-server

3. 依存関係をインストールします：

bun install

設定

すべての設定は任意です。サーバーは適切なデフォルト値で、そのまま動作します。

変数	説明	デフォルト
ARXIV_API_BASE_URL	arXiv API のベース URL。	https://export.arxiv.org/api
ARXIV_REQUEST_DELAY_MS	arXiv API リクエスト間の最小待機時間（ms）。	3000
ARXIV_CONTENT_TIMEOUT_MS	論文本文の取得（HTML のレンダリングと PDF のダウンロード）のタイムアウト（ms）。	30000
ARXIV_API_TIMEOUT_MS	API 検索／メタデータリクエストのタイムアウト（ms）。ミラーが有効な場合、ミラーに論文が保存されていれば応答が返るまでに、バージョン指定のない arxiv_read_paper がメタデータの検索（キューでの待機を含む）に費やす最長時間でもあります。	15000
ARXIV_READ_TIMEOUT_MS	1 回の arxiv_read_paper 呼び出しに割り当てる時間（ms）。メタデータの検索、すべてのコンテンツリクエストと再試行、PDF のテキスト抽出が含まれます。MCP クライアントのリクエストタイムアウト（デフォルトでは 60 秒）より短くしてください。	50000
ARXIV_MIRROR_ENABLED	ローカルの OAI-PMH メタデータミラーを有効にします。	false
ARXIV_MIRROR_PATH	ミラー用 SQLite のパス。	./data/arxiv-mirror.db
ARXIV_MIRROR_REFRESH_CRON	プロセス内での毎日の更新に使う UTC cron 式（HTTP モードのみ）。	未設定
ARXIV_MIRROR_FALLBACK_LIVE	ローカルで ID が見つからない場合、ライブ API にフォールバックします。	true
ARXIV_MIRROR_RECENT_DAYS_LIVE	正の値を指定すると、sort_by=submitted を使った降順のクエリをライブ API に送信します。0 を指定すると無効になります。	2
ARXIV_MIRROR_OAI_BASE_URL	arXiv OAI-PMH エンドポイントのベース URL。	https://oaipmh.arxiv.org/oai
ARXIV_MIRROR_OAI_REQUEST_DELAY_MS	OAI-PMH リクエスト間の最小待機時間（ms）。	3000
ARXIV_MIRROR_REFRESH_TIMEOUT_MS	1 回のスケジュール更新に割り当てる時間（ms）。	7200000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	auto、stateful、または stateless。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
OTEL_ENABLED	OpenTelemetry の計装（スパン、メトリクス、完了ログ）を有効にします。	false

任意のオーバーライド設定の全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  

オプション：ローカルミラー

単一の送信元 IP を経由するセルフホスト型のデプロイでは、arXiv の約 3 秒のクローラー待機時間により、同時に利用するユーザーのリクエストが直列化されます。オプションのローカルミラーを使うと、OAI-PMH 経由で取得した SQLite + FTS5 ストアからデータを提供することで、arxiv_search_papers と arxiv_get_metadata に対するレート制限の影響を回避できます。arxiv_read_paper は常に本文をライブで取得します。全文の収集は arXiv のデータポリシーに反するためです。また、メタデータはライブ検索に失敗した場合、またはバージョン指定のない ID について ARXIV_API_TIMEOUT_MS を過ぎても検索が完了していない場合に限り、ミラーから取得します。読み込まれる保存済みバージョンは、次回更新まで arXiv の最新バージョンより古い可能性があります。

デフォルトでは無効です。有効にするには：

# 1. Cold-start harvest (~4.4h sequential). One-time per installation.
#    Waits out arXiv outages; Ctrl+C stops it, and a rerun resumes from its checkpoint.
bun run mirror:init

# 2. Enable the mirror.
export ARXIV_MIRROR_ENABLED=true

# 3. Start the server — reads switch to the mirror once the harvest completes.
bun run start:http

npm からインストールした場合、mirror:* コマンドはプロジェクトではなくパッケージに属します。パッケージディレクトリで実行するか（bun run --cwd node_modules/@cyanheads/arxiv-mcp-server mirror:init）、プロジェクトのルートからスクリプトを直接実行してください（bun node_modules/@cyanheads/arxiv-mcp-server/scripts/arxiv-mirror-init.ts）。ARXIV_MIRROR_PATH には node_modules の外部にある絶対パスを設定してください。サーバーが読み込むパスと同じものを設定すれば、再インストール後もミラーが保持されます。 bun run mirror:refresh（cron/systemd/launchd、または HTTP モードの ARXIV_MIRROR_REFRESH_CRON）で最新の状態に保ち、bun run mirror:verify で確認してください。更新が中断された場合、次回の実行ではチェックポイントを記録した最後の日付から再開し、その日を再読み込みします。プロセス内で実行される更新が、開始した日を抜ける前に ARXIV_MIRROR_REFRESH_TIMEOUT_MS の予算を使い切った場合は、次回の実行で停止した位置から再開します。リリースによってミラーのスキーマが変わると、書き込みプロセスがファイルをその場で移行するまで、サーバーはライブ API から応答します。再収集は行いません。HTTP モードで ARXIV_MIRROR_REFRESH_CRON を設定している場合、サーバーがその更新を自動で開始します。それ以外の場合は、bun run mirror:refresh または bun run mirror:verify を実行してください。一度にファイルを移行できる書き込みプロセスは1つだけです。その間に開始したミラーコマンドは何も変更せず、移行を実行中のプロセス名を示して終了コード75で終了します。移行が完了したら、コマンドを再実行してください。スキーマ v3 のミラーは、次に書き込みプロセスが開いたときにこの方法で v4 に移行します。カテゴリテーブルに列を追加して値を入力し、5つの日付インデックスを再構築します。フルサイズのミラーでは数秒ではなく数分（約5分）かかり、最大約450 MBの WAL と、約9％増加するファイルを保存するための空きディスク容量が必要です。スキーマ v4 のミラーも同じ方法で v5 に移行します。テキストに ' または " を含む各論文を引用符に置き換えます。対象は320万件中約120万件です。その後、検索で使用するカテゴリインデックスを再構築します。フルサイズのミラーでは、ホストの負荷に応じて約4.5～7.5分かかり、WAL は最大約160 MB、ファイルは約10％増加します。1.7.1以前にロールバックして更新すると、更新によって書き換えられる論文にはそれらの参照が再び保存されます。その後、新しいバージョンに戻したら、ファイルに対して UPDATE schema_version SET version = 4 を実行し、続けて bun run mirror:verify を実行して修復をやり直してください。

ミラーの検索では FTS5 BM25 で順位付けするため、sort_by=relevance の結果はライブ API とは上位の項目が異なります。フリーテキストの語句を指定しないミラー検索は、カテゴリコードを1つだけで絞り込む場合に限り、件数を正確に返します。複数のコード（cat:cs、2つのカテゴリ）にまたがる検索、または投稿日の範囲のみを指定する検索では、件数のカウントは50,000で打ち切られます。合計がこの値に達すると、totalFoundIsLowerBound: true が付加され、件数が50,000以上であることを示します。次の検索はライブ API に切り替わります。sort_by=submitted の降順（ARXIV_MIRROR_RECENT_DAYS_LIVE が正の値の場合）、フリーテキスト語句が50,000件以上の論文に一致する検索、ミラーがフィルターとして適用できない cat: または submittedDate: 演算子を含むクエリ（残りの部分と OR またはスペースで結合されている場合、あるいは ANDNOT の右側にある場合）、またはそれらの演算子を取り除いた後に ANDNOT の項だけが残るクエリ、対応する開き括弧または閉じ括弧がないクエリ、値のないフィールドプレフィックス（ti: x、ti:）、空の引用句、照合対象が何も残らないクエリ（()）、rn:、id:、または lastUpdatedDate: 演算子を含むクエリ、不正な形式の submittedDate: を含むクエリ、より長い引用句の外にある、arXiv のインデックスで除外される語（of、the、and、…）を含むクエリ、存在しないカテゴリを指定する cat: ワイルドカード（cat:zzz.*）、およびバージョンを固定したリクエスト（ミラーに保存されるのは最新版のみ）です。

Docker

docker build -t arxiv-mcp-server .
docker run --rm -p 3010:3010 arxiv-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモード、および /var/log/arxiv-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール／リソースを登録し、オプションのミラー更新スケジューラーを起動します。
src/config	サーバー固有の環境変数を Zod で解析・検証します。
src/mcp-server/tools/definitions	ツール定義（*.tool.ts）です。
src/mcp-server/resources/definitions	リソース定義（*.resource.ts）です。
src/services/arxiv	ArxivService — arXiv API のライブクライアント（検索、メタデータ、HTML）と、ワーカースレッドでの PDF テキスト抽出（pdf-text.ts）です。
src/services/arxiv/mirror	オプションの OAI-PMH ミラーです。ハーベスター、SQLite + FTS5 ストア、クエリトランスレーター、実行プログラムが含まれます。
skills/arxiv-guide	サーバーをインストールしたエージェントに公開され、MCP 経由で提供されるエージェントスキルです。引用から ID への解決、検索ゲート、バージョンごとの読み取り、セクション単位の読み取りワークフローを扱います。
scripts/arxiv-mirror-*.ts	ミラーのライフサイクルスクリプト（init、refresh、verify）です。scripts/tsconfig.json により、@/ インポートはソースでは src/、インストール環境では dist/ に解決されます。
tests/	ユニットテストと統合テストです。
docs/	設計ドキュメントとディレクトリ構成です。

開発ガイド

開発ガイドラインとアーキテクチャ上の規則については、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使わないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使ってください。
• arXiv API はレート制限を含め、すべての応答で HTTP 200 を返します。そのため、解析前にコンテンツタイプと本文を確認してください。
• arXiv の生の応答を検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足しているフィールドを捏造しないでください。

コントリビューション

Issue を歓迎します。提出前にチェックを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。