Skip to main content
Glama
arxiv-mcp-server

arxiv-mcp-server

by cyanheads

Version License Docker MCP SDK npm TypeScript

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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


工具

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

工具名称

描述

arxiv_search

按查询搜索 arXiv 论文,支持类别和排序筛选。

arxiv_get_metadata

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

arxiv_read_paper

从 arXiv 论文的 HTML 渲染中获取全文内容;若无渲染版本,则从 PDF 获取。

arxiv_list_categories

列出 arXiv 类别体系,可按组筛选。

使用带字段前缀和布尔运算符的自由文本查询来搜索论文。

  • 字段前缀: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: arxiv-reader-mcp

资源

URI 模式

描述

arxiv://paper/{paperId}

按 arXiv ID 获取论文元数据。旧式 ID 中的斜杠需进行百分号编码——arxiv://paper/hep-th%2F9901001。

arxiv://categories

完整的 arXiv 类别体系。

特性

基于 @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"]
    }
  }
}

前提条件

安装

  1. 克隆仓库:

git clone https://github.com/cyanheads/arxiv-mcp-server.git
  1. 进入目录:

cd arxiv-mcp-server
  1. 安装依赖:

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 搜索/元数据请求超时(毫秒)。

15000

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

将此窗口内的 sortBy=submitted 降序查询路由到实时 API。

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_AUTH_MODE

认证模式:none、jwt 或 oauth。

none

MCP_LOG_LEVEL

日志级别(RFC 5424)。

info

运行服务器

本地开发

  • 构建并运行:

    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

项目结构

目录

用途

src/mcp-server/tools/definitions/

工具定义(*.tool.ts)。

src/mcp-server/resources/definitions/

资源定义(*.resource.ts)。

src/services/arxiv/

ArxivService — 实时 arXiv API 客户端(搜索、元数据、HTML)。

src/services/arxiv/mirror/

可选的 OAI-PMH 镜像 — 采集器、SQLite + FTS5 存储、查询转换器、运行器。

src/config/

使用 Zod 进行环境变量解析和验证。

scripts/arxiv-mirror-*.ts

镜像生命周期脚本(init、refresh、verify)。

tests/

单元测试和集成测试。

docs/

设计文档和目录结构。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要版本:

  • 处理器抛出异常,框架捕获——工具逻辑中不使用 try/catch

  • 使用 ctx.log 进行领域特定日志记录

  • 速率限制由 ArxivService 管理——不要为每个工具添加延迟

  • arXiv API 对所有请求都返回 HTTP 200——请检查 content-type 和响应体

贡献

欢迎提交 Issue 和拉取请求。提交前请运行检查:

bun run devcheck
bun test

许可证

Apache-2.0 — 详情请参阅 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers