arxiv-mcp-server

公開ホスト型サーバー: https://arxiv.caseyjhand.com/mcp

ツール

arXivの論文を検索・閲覧するための4つのツール:

arxiv_search

フィールドプレフィックスとブール演算子を使用したフリーテキストクエリで論文を検索します。

• フィールドプレフィックス: ti:(タイトル)、au:(著者)、abs:(抄録)、cat:(カテゴリ)、all:(全フィールド)

• ブール演算子: AND、OR、ANDNOT

• オプションのカテゴリフィルタ、並べ替え(関連度、提出日、更新日)、ページネーション

• カテゴリにはリーフコード(cs.CL)またはアーカイブ全体(astro-ph、cs、math)を指定できます。アーカイブ名のみを指定した場合、その主題クラスに加えて、細分化される前に登録されたレガシーなフラット論文も対象になります。

• submitted_from / submitted_to は提出日(両端を含む、UTC YYYY-MM-DD)の範囲を指定します。連続するウィンドウは一致結果を隙間なくカバーします。ちょうど日付の変わり目に提出された論文は両方のウィンドウに含まれるため、IDで重複排除してください。これにより、10,000件のページネーション上限を超えた結果にも到達できます。

• 実際に検索されたクエリを、すべてのフィルタを反映した形で返します。これを再実行すると同じ結果セットが再現されます。

• 1リクエストあたり最大50件の結果を、抄録を含む完全なメタデータとともに返します。

arxiv_get_metadata

既知のarXiv IDを指定して、1件以上の論文の完全なメタデータを取得します。

• 1回のリクエストで最大10件の論文をまとめて取得

• バージョン付き(2401.12345v2)とバージョンなし(2401.12345)の両方のIDを受け付けます

• レガシーID形式(hep-th/9901001)にも対応

• 見つからなかったIDは、見つかった論文とは別に報告します

arxiv_read_paper

arXiv論文の本文全体を読み取ります。

• 最初にarXivネイティブのHTML、次にar5iv、最後にPDFから抽出したテキストを試します。どのソースが応答したかはsourceフィールドに報告されます。

• HTMLのヘッダーや定型文を除去し、MathMLをドル記号で区切られたLaTeX($…$はインライン、$$…$$はブロック)に変換するため、文字数の予算を論文コンテンツに集中させられます。

• 生のHTMLを返します。解析や抽出は行わず、LLMがコンテンツを直接解釈します。PDFから抽出した本文はプレーンテキストです。散文は信頼できますが、数式、表、見出し構造は平坦化されます。

• max_characters のデフォルトは100,000です。1回の呼び出しで論文全体を取得するにはnullを渡します。数式の多い論文では生のHTMLが500KB〜3MB以上になり、ほとんどのクライアントが1回のツール結果として受け入れられるサイズを超えます。代わりにstartでページングしてください。

arxiv_list_categories

発見のためにarXivのカテゴリコードと名前を一覧表示します。

• 8つのトップレベルグループ(cs、math、physics、q-bio、q-fin、stat、eess、econ)にわたる約155のカテゴリ

• 結果を絞り込むためのオプションのグループフィルタ

• 静的データのため、常に成功します

Related MCP server: arxiv-reader-mcp

リソース

機能

@cyanheads/mcp-ts-core上に構築:

• 宣言的なツール定義 — ツールごとに1ファイルで、フレームワークが登録と検証を処理

• 全ツールにわたる統一されたエラーハンドリング

• プラグイン可能な認証(none、jwt、oauth)

• オプションのOpenTelemetryトレーシングを備えた構造化ロギング

• 同じコードベースからローカル(stdio/HTTP)で実行

arXiv固有:

• 読み取り専用で認証は不要 — arXiv APIは無料、メタデータはCC0

• arXivの3秒クロール遅延を強制するレート制限付きリクエストキュー

• レート制限時の適応的クールダウン(5秒 → 10秒 → 20秒 → 30秒)、Retry-Afterを尊重

• 一時的な障害に対する指数バックオフ付きリトライ

• コンテンツのフォールバックチェーン: arXivネイティブHTML → ar5iv → PDFテキスト抽出(両方のHTMLレンダリングはLaTeXMLを実行するため、一緒に失敗する傾向があります。PDFはすべての論文が持つ成果物であり、ar5ivの停止時にも読み取りを失敗させずにカバーします)

• arXivのカテゴリ分類全体を静的データとして埋め込み

• オプションのローカルOAI-PMHメタデータミラー(SQLite + FTS5) — オプトイン方式で、arxiv_searchとarxiv_get_metadataのレート制限の影響を排除します。オプション: ローカルミラーを参照。

はじめに

公開ホスト型インスタンス

公開インスタンスはhttps://arxiv.caseyjhand.com/mcpで利用できます。インストールは不要です。Streamable HTTP経由で任意のMCPクライアントから接続してください:

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

セルフホスト / ローカル

MCPクライアントの設定(例: claude_desktop_config.json)に追加します:

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

前提条件

• Bun v1.3.0以上。

インストール

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

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

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

cd arxiv-mcp-server

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

bun install

設定

すべての設定はオプションです。サーバーは適切なデフォルト値でそのまま動作します。

サーバーの実行

ローカル開発

• ビルドして実行:

  bun run build
  bun run start:http   # or start:stdio

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

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

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

単一の出口IPの背後にあるセルフホスト環境では、arXivのIPあたり約3秒のクロール遅延により、同時ユーザーが直列化されます。オプションのローカルミラーは、OAI-PMH経由で収集したSQLite + FTS5ストアから提供することで、arxiv_searchとarxiv_get_metadataのレート制限の影響を排除します。arxiv_read_paperは引き続きライブAPIを使用します。全文コンテンツの収集はarXivのデータポリシーで禁止されています。

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

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation.
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

毎日の増分更新(差分は小さく、所要時間はarXivのOAI-PMHページペーシングに依存)は次の方法で行います:

bun run mirror:refresh   # wire to cron / systemd timer / launchd, OR
                         # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process)
bun run mirror:verify    # schema version + PRAGMA integrity_check / quick_check

スキーマアップグレード。 ミラーはスキーマバージョンを記録し、より新しいサーバーが最初に開いたときにその場で自動移行します — 再ハーベストも、別途のオペレーター操作も不要です。comment と journal_ref を全文検索インデックスに追加したアップグレード（#37）は、すでに保存されている行からそのインデックスを再構築するため、co: および jr: 検索は、アップグレード前にハーベストされたミラーに対して解決されます。再構築は起動時、ストアが最初の読み取りに応答する前に実行され、mirror migration v2→v3 (fts rebuild) の進行状況の行を随時ログに記録します — 全文コーパスのミラーでは、アップグレード後の最初の起動が通常より著しく長くなると想定してください。中断された再構築は、半分適用されたまま放置されるのではなく、次回のオープン時に再実行されます。bun run mirror:verify は、ファイルが保持するスキーマバージョンを出力し、移行が完了していない場合は非ゼロで終了します。

動作上の注意。 ランキングの相違：FTS5 BM25はarXivの内部ランキングとは異なるため、ミラーに対する sortBy=relevance は、ライブAPIとは異なるtop-Kを返します。ARXIV_MIRROR_RECENT_DAYS_LIVE 日以内で submitted 降順にソートされたクエリは、夜間更新のギャップをカバーするためにライブAPIにルーティングされます。更新の回復力：最初のコールドハーベストが完了した後、進行中または失敗した日次更新は、既存のデータセットをミラーから提供し続けます — arxiv_search と arxiv_get_metadata は更新ウィンドウ中にライブAPIにフォールバックしません（#21）。スケジュールされたHTTPモードの更新は子プロセスで実行されるため、ハーベストの同期SQLite書き込みがリクエストイベントループをブロックすることはありません — 検索とメタデータは全体を通して応答性を維持します（#22）。ミラーは最新バージョンのみを保存します。バージョンごとの読み取りは引き続きライブAPIを使用します。完全な設計については #12 を参照してください。

Docker

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

プロジェクト構造

開発ガイド

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

• ハンドラーがスローし、フレームワークがキャッチする — ツールロジックに try/catch は不要

• ドメイン固有のログには ctx.log を使用

• レート制限は ArxivService が管理 — ツールごとの遅延を追加しない

• arXiv APIはすべてに対してHTTP 200を返す — content-typeとレスポンスボディを確認

コントリビューション

Issueとプルリクエストを歓迎します。提出前にチェックを実行してください：

bun run devcheck
bun test

ライセンス

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