# @cyanheads/arxiv-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/

版本：1\.8\.2
npm 元数据更新时间：2026-11-08T18:45:02.758Z
中文译文更新时间：2026-11-11T06:02:42.914Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/arxiv-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/arxiv-mcp-server#readme
源码仓库：https://github.com/cyanheads/arxiv-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，188 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：8 个
- 首次发布：2026-03-30T15:35:40.012Z
- 最新版本发布：2026-11-08T18:45:02.591Z
- 近 30 天下载量：4727（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

搜索arXiv,取出纸质元数据,通过MCP读取全文内容. (原始内容存档于2012-10-12). STIO or Streamable HTTP.

## 安装

```sh
npm install @cyanheads/arxiv-mcp-server
```

也可以使用：`pnpm add @cyanheads/arxiv-mcp-server`、`yarn add @cyanheads/arxiv-mcp-server`、`bun add @cyanheads/arxiv-mcp-server`

## README

# @cyanheads/arxiv-mcp-服务器

**搜索arXiv,取出纸质元数据,通过MCP读取全文内容. (原始内容存档于2012-10-12). STIO or Streamable HTTP.**

4个工具 • 2个资源

[![Version](https://img.shields.io/badge/Version-1.8.2-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/arxiv-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/arxiv-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/arxiv-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-%5E7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/arxiv-mcp-server/releases/latest/download/arxiv-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=arxiv-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXJ4aXYtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22arxiv-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Farxiv-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**公共主机服务器 :** [https://arxiv.caseyjhand.com/mcp (中文(简体) )](https://arxiv.caseyjhand.com/mcp)

* * *

## 概览

arXiv文件、元数据以及ArXiv API及其审调处-PMH元数据反馈的全文。 按查询、类别和提交日期来搜索文件;通过ID获取结构化元数据;并读取HTML和PDF制成的全纸文本,自动回落。 运行为 stdio 进程,本地可流的 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` 使用一个代码( e)`cs.CL`)或整个档案(`astro-ph`, (中文(简体) ), `cs`, (中文(简体) ), `math`(中文(简体) )
-   查询语法遵循 arXiv 的: 空间分隔的名词与 `OR` (写出) `AND` 以要求每个术语),运算符只是大写,所有三个词都有一个优先级归为右(`a AND b OR c` 实值 `a AND (b OR c)`. 引文使用过时参数coauthors (帮助) 多字专题 (简体中文)`"graph neural networks" AND cat:cs.LG`)并在过滤器前加括号;arXiv 忽略了常见的单词,例如 `of` 财务报告和审定财务报表 `the` 引用的短语之外
-   排序为 `sort_by` (单位:千美元)`relevance` 编号 : `submitted` 编号 : `updated`,无论如何;arXiv自己的 `submittedDate` 编号 : `lastUpdatedDate` 改为 `submitted` 编号 : `updated`和 `sort_order`,与 `submitted_from` 编号 : `submitted_to` 包括世界协调时 `YYYY-MM-DD` 界限;每次呼叫最多50个结果(较大) `max_results` 返回 50时
-   arXiv只服务于一个查询的第一个10,000个结果; a `start` 1万个失败 `start_beyond_result_limit`。使用日期窗口更进一步
-   输出回放有效的查询,总匹配计数,以及页面偏移;空页带回取回的指引而不是出错. 总共为一层(当地镜子计为5万) `totalFoundIsLowerBound: true`

* * *

### `arxiv_get_metadata` 工具

-   最多需要100张身份证 查一下前10张 `remaining_ids` 下一个电话的 `paper_ids`。任何接受的拼写中重复的ID会被查一次,而不同版本的一张纸则分开
-   接受版本( E)`2401.12345v2`),未转录,以及2007年之前(`hep-th/9901001`身份证,可选 `arXiv:` 前缀或 arxiv.org `abs` 编号 : `pdf` 编号 : `html` 網址
-   返回已找到的纸外加打入的 `not_found[]` (单位:千美元)`not_in_arxiv` 编号 : `version_not_in_mirror` 编号 : `version_not_served` 编号 : `live_lookup_failed` 编号 : `invalid_id`其余部分; `version_not_served` arXiv 的 API 对 HTTP 500 的回答及其 `detail` 命名最新版本。 与当地的镜子, `live_lookup_failed` 标记一个识别符 镜像缺少其活视镜失败; 镜像服务的文件仍然回来
-   失败者 `invalid_id` 当没有很好的身份证, `no_match` 当每一个身份缺失, `version_unavailable` 当一个版本只能在活的 API 上达到时,并且 `version_not_served` 当每个ID是一个版本 arXiv 将不会服务

* * *

### `arxiv_read_paper` 工具

-   Tries 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` 页:1
-   `paper_id` 接受相同的 ID 拼写为 `arxiv_get_metadata`
-   失败者 `invalid_id`, (中文(简体) ), `no_match` (arXiv没有这种文件,或没有这种版本), `content_unavailable` (无渲染、无PDF), `pdf_extraction_failed` (PDF没有文本层或不解析), `version_unavailable` (arXiv是无法接触到的,当地镜像持有被钉住的ID的另一个版本),或 `version_not_served` (被取代的2007年前版本arXiv将不服务;命名最新版本和本版本的PDF)

* * *

### `arxiv_list_categories` 工具

-   ~155个类别,分布在8个最高级别的团体(`cs`, (中文(简体) ), `econ`, (中文(简体) ), `eess`, (中文(简体) ), `math`, (中文(简体) ), `physics`, (中文(简体) ), `q-bio`, (中文(简体) ), `q-fin`, (中文(简体) ), `stat`(中文(简体) )
-   可选 `group` 过滤到缩小结果
-   静态数据——总是成功的

* * *

### `arxiv://paper/{paperId}` 资源

-   `paperId` 接受相同的 ID 拼写为 `arxiv_get_metadata`; %-encode 一个遗留的ID的斜线(`arxiv://paper/hep-th%2F9901001`(中文(简体) )
-   失败者 `empty_id`, (中文(简体) ), `invalid_id`, (中文(简体) ), `no_match`, (中文(简体) ), `version_unavailable`,或 `version_not_served`

* * *

### `arxiv://categories` 资源

-   回返 `{ categories: [...] }`,一个平面阵列,其中 `code` 编号 : `name` 编号 : `group` 每个条目
-   无参数;24h可缓存

## 特征

建造在 [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio和可流式的 HTTP 传输器,可插接式(`none` 编号 : `jwt` 编号 : `oauth`),可互换存储(`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2/D1`),结构化记录,可选择的OpenTeleometry tracking.

arXiv 特异性:

-   只读, 不需要认证
-   请求队列执行 arXiv 的 三秒爬行延迟; 速率限制响应在冷却后迅速失败
-   纸张文本从 arXiv HTML 返回到 ar5iv 到 PDF 提取
-   作为静态数据嵌入的完整arXiv分类
-   可选的本地审调处-PMH元数据镜像(SQLite + FTS5)可以去除搜索和元数据的限速曝光. 见 [可选: 本地镜像](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/#readme-optional-local-mirror)

方便代理输出 :

-   `arxiv_read_paper` 名称 `source`· ; `arxiv_search_papers` 响应有效的查询
-   `arxiv_get_metadata` 返回已输入的已找到的文档 `not_found[]` 每个错失的原因
-   类型 `source` 财务报告和审定财务报表 `not_found[].reason` enums 允许调用数据分支

## 开始

### 公共托管实例

可在 `https://arxiv.caseyjhand.com/mcp` 无需安装。 通过可流式HTTP将 MCP 客户端指向它 :

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

### 自有/当地

在您的 MCP 客户端配置文件中添加以下内容 .

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

或者用 npx( 不需要 Bun) :

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

或与道克相会:

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

对于可流式HTTP,设置传输并启动服务器:

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

### 先决条件

-   [Bun v 1.4.4 (单位:千美元)](https://bun.sh/) 或更高(或Node.js v24+).

### 安装

1.  **清除仓库 :**

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

2.  **导航到目录 :**

```sh
cd arxiv-mcp-server
```

3.  **安装依赖性 :**

```sh
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` | 其中一项的时间预算 `arxiv_read_paper` 调用 – 其元数据查询,每个内容请求和重试,以及 PDF 文本提取 (ms). 保存在您的 MCP 客户端的请求超时( 默认为 60 s) 下 . | `50000` |
| `ARXIV_MIRROR_ENABLED` | 启用本地审调处- PMH 元数据镜像 . | `false` |
| `ARXIV_MIRROR_PATH` | SQLite 路径用于镜像 . | `./data/arxiv-mirror.db` |
| `ARXIV_MIRROR_REFRESH_CRON` | UTC cron 表达式用于进程内每日刷新(仅HTTP模式). | 未设定 |
| `ARXIV_MIRROR_FALLBACK_LIVE` | 接通现场API 接听本地的身份证检查小姐. | `true` |
| `ARXIV_MIRROR_RECENT_DAYS_LIVE` | 正值发送 `sort_by=submitted`将查询输入实时API; `0` 禁用 . | `2` |
| `ARXIV_MIRROR_OAI_BASE_URL` | arXiv 审调处-PMH端点基础URL. | `https://oaipmh.arxiv.org/oai` |
| `ARXIV_MIRROR_OAI_REQUEST_DELAY_MS` | 审调处-公共卫生部之间请求之间的最小延迟(ms). | `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` | Auth 模式 : `none`, (中文(简体) ), `jwt`,或 `oauth`。 。 。 . | `none` |
| `MCP_LOG_LEVEL` | 日志级别(RFC 5424). | `info` |
| `OTEL_ENABLED` | 启用 [OpenTelemet 仪器](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (日文、度量、完成日志). | `false` |

见 [`.env.example`](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/.env.example) 用于完整可选覆盖列表.

## 运行服务器

### 地方发展

-   **构建和运行 :**
    
    ```sh
    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:http
    # or
    bun run start:stdio
    ```
    
-   **运行检查和测试 :**
    
    ```sh
    bun run devcheck   # Lint, format, typecheck, security audit
    bun run test       # Vitest test suite
    ```
    

### 可选: 本地镜像

对于一个Egress IP背后的自备部署,ARXIV的SQLite + FTS5 镜像可选 SQLite + FTS5 镜像服务 `arxiv_search_papers` 财务报告和审定财务报表 `arxiv_get_metadata` 本地,所以并行用户停止在arXiv的3秒爬行延迟后排队; `arxiv_read_paper` 仍可实时获取纸张文本。 收获一次 `bun run mirror:init` (~4.4h),然后设定 `ARXIV_MIRROR_ENABLED=true`。从 npm 安装、 调度更新、 计划升级中运行它, 且镜像搜索与 API 的活式搜索不同 [文件/备忘录](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/docs/mirror.md)。 。 。 .

### 夹克

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

Dockerfile 默认为 HTTP 传输、 无国籍会话模式和日志到 `/var/log/arxiv-mcp-server`。默认情况下安装了 OpenTeleometry 端端依赖性 `--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` | 可选审调处-PMH镜像-收割机,SQLite + FTS5商店,查询翻译,跑道. |
| `skills/arxiv-guide` | 代理技能发布给安装服务器的代理,并服务于MCP:引用-到ID分辨率,搜索门,版本和分节读取工作流程. |
| `scripts/arxiv-mirror-*.ts` | 镜像生命周期脚本( E)`init`, (中文(简体) ), `refresh`, (中文(简体) ), `verify`(三); `scripts/tsconfig.json` 解决他们的 `@/` 进口到 `src/`,或改为 `dist/` 在安装. |
| `tests/` | 单位与整合测试. |
| `docs/` | 设计文档,本地镜像指南,以及目录结构. |

## 发展指南

见 [`CLAUDE.md`](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/CLAUDE.md) 发展准则和建筑规则。 简本:

-   搬运工投掷,框架渔获量——否 `try/catch` 在工具逻辑中
-   使用 `ctx.log` 请求范围伐木, `ctx.state` 租户范围储存
-   arXiv API 返回 HTTP 200 , 包括速率限制, 因此在解析前检查内容类型和正文
-   验证原始 arXiv 响应 = 与域类型正常化 = 返回输出计划; 永远不编织缺失的字段

## 捐款

问题值得欢迎。 提交前运行检查 :

```sh
bun run devcheck
bun run test
```

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40cyanheads/arxiv-mcp-server/LICENSE) 详细情况.

## 常见问题

### @cyanheads/arxiv-mcp-server 是什么？

搜索arXiv,取出纸质元数据,通过MCP读取全文内容\. \(原始内容存档于2012-10-12\)\. STIO or Streamable HTTP\.

### 如何安装 @cyanheads/arxiv-mcp-server？

在项目目录运行 npm install @cyanheads/arxiv-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 arxiv-mcp-server，可以用 npx arxiv-mcp-server 直接运行。

### @cyanheads/arxiv-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/arxiv-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/arxiv-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/arxiv-mcp-server 可以商用吗？

@cyanheads/arxiv-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/arxiv-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/arxiv-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 4,727 次，日均约 158 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/arxiv-mcp-server 还在维护吗？

最新版本 1\.8\.2 发布于 2026/11/09（2 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/03/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。