arxiv-mcp-server

---

概述

通过 arXiv API 及其 OAI-PMH 元数据源获取 arXiv 论文、元数据和全文。按查询词、类别和提交日期搜索论文；按 ID 获取结构化元数据；并通过 HTML 和 PDF 渲染版本自动回退的方式阅读论文全文。可作为 stdio 进程、本地 Streamable HTTP 服务运行，也可使用上述公共托管端点。

工具

工具	描述
arxiv_search_papers	按查询词搜索 arXiv 论文，支持字段前缀、类别和日期筛选
arxiv_get_metadata	按 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）；运算符只能使用大写形式，且三种运算符的优先级相同，并从右向左分组（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）；每次调用最多返回 50 条结果（将 max_results 设得更大仍只返回 50 条）
• arXiv 对查询仅提供前 10,000 条结果；start 设为 10,000 会导致 start_beyond_result_limit。如需查看更多结果，请使用日期范围
• 输出会回显实际使用的查询、匹配总数和分页偏移量；空页面会提供恢复建议，而非返回错误。如果总数是下限（本地镜像的计数上限为 50,000），则会包含 totalFoundIsLowerBound: true

---

arxiv_get_metadata _工具

• 最多接收 100 个 ID，并查询前 10 个；其余 ID 会放在 remaining_ids 中，供下一次调用的 paper_ids 使用
• 接受带版本号的 ID（2401.12345v2）、不带版本号的 ID，以及 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 对已被取代的 2007 年之前版本返回 HTTP 500，其 detail 会指出最新版本。使用本地镜像时，live_lookup_failed 表示镜像中没有该 ID，且在线查询失败；镜像成功提供的论文仍会返回
• 如果所有 ID 格式都不正确，则返回 invalid_id；如果所有 ID 均未匹配，则返回 no_match；如果某个版本只能通过在线 API 获取，则返回 version_unavailable；如果所有 ID 都是 arXiv 不会提供的版本，则返回 version_not_served

---

arxiv_read_paper _工具

• 依次尝试 arXiv HTML、ar5iv 和 PDF 文本提取；source 字段会报告实际提供内容的来源。PDF 文本为纯文本，因此数学公式、表格和标题会被压平
• ar5iv 每篇论文只保留一个渲染版本，因此 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），可消除搜索和元数据查询的速率限制风险。请参阅可选：本地镜像

便于 Agent 使用的输出：

• 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 请求之间的最短延迟（毫秒）。	3000
ARXIV_CONTENT_TIMEOUT_MS	获取论文正文的超时时间，包括 HTML 渲染和 PDF 下载（毫秒）。	30000
ARXIV_API_TIMEOUT_MS	API 搜索／元数据请求的超时时间（毫秒）。启用镜像后，对于未指定版本的 arxiv_read_paper，这也是在镜像返回已存储论文前等待元数据查询（包括排队）的最长时间。	15000
ARXIV_READ_TIMEOUT_MS	单次 arxiv_read_paper 调用的时间预算，包括元数据查询、每次内容请求和重试，以及 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	正值会向实时 API 发送按 sort_by=submitted 降序排列的查询；0 表示禁用。	2
ARXIV_MIRROR_OAI_BASE_URL	arXiv OAI-PMH 端点基础 URL。	https://oaipmh.arxiv.org/oai
ARXIV_MIRROR_OAI_REQUEST_DELAY_MS	OAI-PMH 请求之间的最短延迟（毫秒）。	3000
ARXIV_MIRROR_REFRESH_TIMEOUT_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。同一时间只能有一个写入程序迁移文件：此时启动的镜像命令不会更改任何内容，并会以状态码 75 退出，同时指出占用迁移的进程；待其完成后重新运行即可。架构 v3 的镜像会在下一次写入程序打开时按此方式迁移到 v4：它会向类别表添加一列并填充数据，然后重建五个日期索引。完整大小的镜像需要几分钟，而不是几秒（约五分钟），并且需要预留磁盘空间：WAL 峰值约为 450 MB，文件会增大约 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 不同。不含自由文本词项的镜像搜索只有在按一个类别代码筛选时才会精确计数；跨多个代码（cat:cs、两个类别）或仅按提交日期范围筛选的搜索，计数上限为 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	发布给安装此服务的 Agent 的 Agent 技能，并通过 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 响应 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

欢迎提交问题。提交前请运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参见 LICENSE。