arxiv-mcp-server

公共托管服务器： https://arxiv.caseyjhand.com/mcp

工具

四个用于搜索和阅读 arXiv 论文的工具：

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 条分页上限获取更多结果的方法

• 回显实际搜索时使用的查询，所有筛选条件均已合并其中——重放该查询可复现相同的结果集

• 每次请求最多返回 50 条结果，包含完整元数据（含摘要）

arxiv_get_metadata

按已知的 arXiv ID 获取一篇或多篇论文的完整元数据。

• 单次请求最多批量获取 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；传入 null 可在一次调用中获取整篇论文。对于数学公式较多的论文，原始 HTML 可能达到 500KB-3MB 以上，超过大多数客户端单次工具结果可接受的大小——请改用 start 分页获取

arxiv_list_categories

列出 arXiv 类别代码和名称，便于发现。

• ~155 个类别，分布在 8 个顶级组（cs、math、physics、q-bio、q-fin、stat、eess、econ）中

• 可选的组筛选，用于缩小结果范围

• 静态数据——始终成功

Related MCP server: Research Server

资源

特性

基于 @cyanheads/mcp-ts-core 构建：

• 声明式工具定义——每个工具一个文件，框架负责注册和验证

• 所有工具统一错误处理

• 可插拔认证（none、jwt、oauth）

• 结构化日志，可选 OpenTelemetry 追踪

• 同一代码库可本地运行（stdio/HTTP）

arXiv 专属特性：

• 只读，无需认证——arXiv API 免费，元数据为 CC0

• 限速请求队列，强制执行 arXiv 的 3 秒抓取延迟

• 限速时自适应冷却（5s → 10s → 20s → 30s），并遵循 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 的约 3 秒每 IP 抓取延迟会使并发用户串行化。可选的本地镜像通过从经 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 返回的 top-K 与实时 API 不同。在 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。