ArXiv MCP Server

arxiv-mcp-server

为 Agent 文献研究提供的本地 MCP 服务。其特色是读取原始 LaTeX 论文各章节、从 arXiv 元数据生成 BibTeX，以及追踪主题。论文保存在本地磁盘。工作流程是：论文 ID → 大纲 → 单个章节 → 引文。搜索是可选功能。

安装

默认安装方式为 uvx arxiv-mcp-server。基于命令的集成需要 uv，它提供 uvx。无需克隆代码仓库或设置 Python 环境。

uvx arxiv-mcp-server

对于接受 mcpServers JSON 格式的客户端（例如 Claude Desktop 和 Kiro），请添加此 stdio 配置。其他客户端可能使用顶层 servers 对象、TOML 或自己的设置界面；请参阅相应客户端的 MCP 文档。

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}

默认论文目录为 ~/.arxiv-mcp-server/papers。如需选择其他目录，请在 args 后追加 "--storage-path", "/absolute/path/to/papers"。

支持的程序包已发布到 PyPI，名称为 arxiv-mcp-server==0.8.2。另有一个无关的 npm 程序包使用了相同名称，因此请勿通过 npm、pnpm 或 npx arxiv-mcp-server 安装此服务。

已列入官方 MCP 注册表，最新版本为 0.8.2。

为什么这不是搜索封装器

搜索、源代码检索、引文图谱和下载分别调用相应的外部服务。本地执行的是文献工作流程：逐个章节阅读作者提交的 LaTeX、从权威 arXiv 元数据导出 BibTeX，并在磁盘上追踪主题。默认情况下，该服务通过 stdio 在本地运行。

各客户端的配置示例（Claude Code、Codex、Hermes、VS Code / Kiro、Claude Desktop、插件）

除非客户端提供单行配置助手，否则请使用上方的默认 JSON。

### Claude Code

为所有项目添加 MCP 服务：

claude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server

如需更丰富的插件集成（安装 MCP 连接以及捆绑的 arXiv 研究技能），请将此仓库注册为市场并安装插件：

claude plugin marketplace add blazickjp/arxiv-mcp-server
claude plugin install arxiv-mcp-server@arxiv-mcp

使用 claude mcp get arxiv 验证直接安装的 MCP 服务。安装插件后，重启 Claude Code 或运行 /reload-plugins。

OpenAI Codex

添加 MCP 服务：

codex mcp add arxiv -- uvx arxiv-mcp-server

或者，将 MCP 连接和捆绑的研究技能作为 Codex 插件安装：

codex plugin marketplace add blazickjp/arxiv-mcp-server
codex plugin add arxiv-mcp-server@arxiv-mcp

使用 codex mcp get arxiv 验证直接安装的 MCP 服务。Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用中的 Codex 共用此 MCP 配置。

Hermes Agent

添加服务，批准发现的工具，并测试已保存的连接：

hermes mcp add arxiv --command uvx --args arxiv-mcp-server
hermes mcp test arxiv

VS Code 和 Kiro

如需更丰富的 Kiro Power 集成，请打开 Powers 面板，选择 添加自定义 Power → 从 GitHub 导入 Power，然后输入：

https://github.com/blazickjp/arxiv-mcp-server

该 Power 会从 mcp.json 安装 MCP 连接，并添加专门的 arXiv 研究指南。偏好手动配置的 Kiro 用户，可以将上面的通用配置放入 .kiro/settings/mcp.json，以用于单个工作区；也可以放入 ~/.kiro/settings/mcp.json，以用于所有工作区。

Claude Desktop 捆绑包

macOS 用户可以从 v0.8.2 版本或最新 GitHub 版本安装捆绑的 .mcpb 扩展：

• Apple Silicon：arxiv-mcp-server-darwin-arm64-0.8.2.mcpb
• Intel：arxiv-mcp-server-darwin-x86_64-0.8.2.mcpb

双击该捆绑包，将其拖入 Claude Desktop，或打开 设置 → 扩展 → 高级设置 → 安装扩展…。该捆绑包包含服务依赖项，需要 CPython 3.11.x。

其他 MCP 客户端

其他客户端可能使用顶层 servers 对象、TOML 或自身的设置界面；请参阅相应客户端的 MCP 文档。直接安装 MCP 服务是最简便的方式。如果还需要引导客户端进行定向搜索、限制阅读范围、遍历引文以及按章节检索 LaTeX 内容的研究工作流，请安装插件。

插件清单

同一 MCP 服务和研究技能已打包，可用于两大主流插件系统：

集成	清单	市场
Claude Code	.claude-plugin/plugin.json	.claude-plugin/marketplace.json
OpenAI Codex / ChatGPT Work	.codex-plugin/plugin.json	.agents/plugins/marketplace.json
Kiro Power	POWER.md	mcp.json
共享 MCP 启动配置	Claude 和仓库本地客户端使用 .mcp.json；Codex 插件使用 .codex-mcp.json	uvx arxiv-mcp-server
共享研究工作流	skills/arxiv-mcp-server/SKILL.md	随任一插件安装

## 如果桌面客户端找不到 `uvx`

桌面应用并不总是继承与终端相同的 PATH。如果 uvx arxiv-mcp-server 在终端中可以运行，但客户端报告 MCP 服务连接失败，请查找可执行文件的绝对路径：

# macOS and Linux
command -v uvx

# Windows PowerShell
(Get-Command uvx).Source

将 "command": "uvx" 替换为返回的绝对路径，然后重启客户端。保持 args 值不变。

如果现有安装缺少较新的工具

uvx 会复用缓存的工具环境。使用受支持的解释器，强制解析当前 PyPI 版本，然后重启 MCP 客户端：

uvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server

如果客户端仍启动较旧的环境，请在其 args 数组中的 "arxiv-mcp-server" 前添加 "--python", "3.11"。

持久安装命令

若要将 arxiv-mcp-server 放入 PATH，而不是通过 uvx 启动：

uv tool install arxiv-mcp-server

如果命令无法立即使用，请运行 uv tool update-shell 并重启终端。之后，使用 "command": "arxiv-mcp-server"，并从 args 中省略包名。

工具

该服务目前提供 19 个工具。

工具	用途	备注
search_papers	按查询、类别、日期和排序方式搜索 arXiv	默认返回 ≤5 条精简结果（abstract_mode=snippet）；远程 arXiv API
get_abstract	根据 arXiv ID 获取元数据和摘要	不会下载论文
download_paper	下载论文并转换为本地 Markdown	优先使用 HTML；PDF 回退使用 [pdf]；force=true 会重新获取；内容默认限制为 12,000 个字符
list_papers	列出本地存储的论文	返回 id、标题、作者、发布日期；使用 compact 仅返回 ID
read_paper	阅读本地存储的论文内容	内容默认限制为 12,000 个字符；支持 start/max_chars/return_full_text
get_paper_outline	分页返回 Markdown 标题大纲	层级章节 ID 稳定
read_paper_section	阅读一个长度受限的 Markdown 章节	按大纲 ID 或唯一标题选择
search_paper_text	在论文中搜索长度受限的段落	提供源文本偏移量；无需 Torch
get_paper_latex	获取长度受限的作者提交版 LaTeX	远程 arXiv 源码归档
list_paper_latex_sections	分页返回 LaTeX 大纲	支持 start 和 max_sections
get_paper_latex_section	阅读一个长度受限的 LaTeX 章节	按大纲 ID 或精确标题选择
citation_graph	获取参考文献和引用该论文的论文	远程 Semantic Scholar API（每篇论文调用 1 次，结果缓存在磁盘上）；可选的免费 API 密钥可提高可靠性
export_citations	导出一个或多个 arXiv ID 的 BibTeX	采用权威 arXiv 元数据
watch_topic	保存或更新 arXiv 主题监视	本地存储；更新时省略 categories 可保留原值，设置 categories: [] 可清除
list_watches	列出已保存的主题监视	只读；不会更新 last_checked
check_alerts	检查已保存的监视是否有新论文	返回上次检查以来的论文
unwatch_topic	删除已保存的主题监视	主题必须完全匹配；不存在时返回 not-found
semantic_search	按语义相似度搜索已下载的论文	需要 [pro]
reindex	重建本地语义索引	需要 [pro]

研究提醒（watch_topic）

使用 watch_topic 保存持续主题监视，使用 list_watches 查看，使用 check_alerts 轮询，并使用 unwatch_topic 删除。

更新现有监视时（topic 字符串相同）：

• 省略 categories → 保留已存储的类别筛选条件（以及其他未更改的字段）。
• 传入 categories: [] → 清除类别筛选条件。
• 传入非空列表 → 替换已存储的筛选条件。

创建时：省略 categories 会存储一个空列表（不按类别筛选）。

search_papers 查询指南

工具架构有意保持简短。有关查询教程、类别目录和工作流示例，请查看本节（而非始终加载的 MCP 描述）。

查询构建

• 使用引号括起短语进行精确匹配："multi-agent systems"、"neural networks"
• 使用 OR 组合相关概念："AI agents" OR "software agents"
• 按字段搜索：ti:"exact title phrase"、au:"author name"、abs:"keyword"、cat:cs.LG
• 使用 ANDNOT 排除："machine learning" ANDNOT "survey"
• 优先使用 2–4 个核心概念，而非冗长的关键词列表

高级模式

• 字段 + 短语：ti:"transformer architecture"
• 多个字段：au:"Smith" AND ti:"quantum"
• 排除项："deep learning" ANDNOT ("survey" OR "review")
• 宽泛 + 具体："artificial intelligence" AND (robotics OR "computer vision")

类别筛选（推荐用于提高相关性）

计算机科学：cs.AI（AI）、cs.LG（ML）、cs.CL（NLP）、cs.CV（视觉）、cs.MA（多 Agent）、cs.RO（机器人学）、cs.NE（神经网络／进化计算）、cs.IR（信息检索）、cs.HC（人机交互）、cs.CR（安全）、cs.DB（数据库）

统计学与数学：stat.ML、stat.AP、math.OC、math.ST

物理学及其他：quant-ph、eess.SP、eess.AS、physics.data-an

有效示例

• ti:"reinforcement learning"，搭配 categories: ["cs.LG", "cs.AI"]
• au:"Hinton" AND "deep learning"，搭配 categories: ["cs.LG"]
• "multi-agent" ANDNOT "survey"，搭配 categories: ["cs.MA"]
• abs:"transformer" AND ti:"attention"，搭配 categories: ["cs.CL"]

日期与排序

• 日期格式为 YYYY-MM-DD（date_from / date_to）
• 默认 sort_by 为 relevance；监控最新内容时使用 date
• 基础性研究：date_to: "2010-12-31"，搭配标题／摘要字段搜索

结果数量、摘要与分页

• 默认 max_results 为 5（上限 50）。如需更大的页面，请传入明确的值。
• abstract_mode：snippet（默认，约 280 个字符，截断时标记为 … [truncated]）、full（完整摘要）或 none（省略摘要）。其他元数据（标题、作者、类别、日期、URL）始终会返回。
• 响应会报告 total_results（语料库命中数）、returned、has_more、start、next_start 和 abstract_mode
• 下一页请使用相同的 abstract_mode，并传入 start=next_start
• arXiv 要求请求间隔约为 3 秒（由服务端处理）；遇到速率限制错误时，请等待约 60 秒

搜索并查看论文

请让 MCP 客户端调用 search_papers：

{
  "query": "\"Kolmogorov-Arnold Networks\"",
  "categories": ["cs.LG", "cs.AI"],
  "sort_by": "date"
}

默认最多返回 5 条精简结果，并附带摘要片段。若需要在搜索响应中获取完整摘要，请使用 "abstract_mode": "full"；也可以先进行精简搜索，再对单篇论文调用 get_abstract：

{
  "paper_id": "2404.19756"
}

对于已通过 abstract_mode=full 返回的论文，请勿再次调用 get_abstract。

下载并阅读全文

使用以下参数调用 download_paper：

{
  "paper_id": "2404.19756"
}

省略 max_chars 时，会返回有长度限制的第一段内容（默认 12,000 个论文字符）。缓存中的论文会立即返回。传入 "force": true 可重新下载并覆盖本地 Markdown 文件及其 sidecar 文件（HTML 提取器版本变更时也会自动执行此操作）。

然后使用 read_paper 分页读取缓存内容：

{
  "paper_id": "2404.19756",
  "start": 0
}

或者从之前的内容块继续读取：

{
  "paper_id": "2404.19756",
  "start": 12000
}

大型内容响应会包含 content_length、returned_chars、next_start、is_truncated，以及（截断时）包含下一次调用说明的 next_retrieval。将 next_start 传入下一次调用的 start，即可继续阅读。传入明确的 max_chars 可覆盖默认内容块大小；也可以传入 "return_full_text": true，选择返回先前那种不受长度限制的完整论文内容。

迁移说明（默认返回有界内容）

以前，在 download_paper / read_paper 中省略 max_chars 会返回论文的全文。现在默认返回 12,000 个字符的分块，以避免单次 MCP 工具调用耗尽客户端上下文窗口。

需求	调用
第一个有界分块（新默认值）	{ "paper_id": "…" }
继续阅读	{ "paper_id": "…", "start": <next_start> }
自定义分块大小	{ "paper_id": "…", "max_chars": 5000 }
旧版无界行为	{ "paper_id": "…", "return_full_text": true }

已传入 max_chars 的客户端不受影响。只有依赖省略 max_chars 即返回全文行为的调用方，才需要添加 return_full_text: true，或通过 next_start 分页。

按章节读取原始 LaTeX

调用 get_paper_latex：

{
  "paper_id": "1706.03762"
}

使用 list_paper_latex_sections 获取章节大纲的第一页：

{
  "paper_id": "1706.03762",
  "start": 0,
  "max_sections": 100
}

然后使用该大纲中的 ID 调用 get_paper_latex_section：

{
  "paper_id": "1706.03762",
  "section_id": "3.2",
  "max_chars": 12000
}

返回内容前，会先验证 LaTeX 存档、限制其大小，并将其缓存在本地。

可选依赖项

选择与所需功能相匹配的安装变体：

# Base server
uv tool install arxiv-mcp-server

# Base server plus PDF conversion
uv tool install "arxiv-mcp-server[pdf]"

# Base server plus local semantic search
uv tool install "arxiv-mcp-server[pro]"

如果已安装基础工具，请重新安装所选变体：

uv tool install --force "arxiv-mcp-server[pdf]"

pdf extra 会为没有可用 arXiv HTML 的论文安装 pymupdf4llm 和 pymupdf-layout。pro extra 会为 semantic_search 和 reindex 添加本地嵌入依赖项；语义搜索仅适用于已下载到配置的存储目录中的论文。

对于需要进行 PDF 转换的较旧论文，请使用其 PDF extra 运行软件包：

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "arxiv-mcp-server[pdf]",
        "arxiv-mcp-server"
      ]
    }
  }
}

内置提示词

该服务提供七种 MCP 提示词工作流。提示词是否可用取决于客户端；该服务提供工作流说明，但不会运行单独的模型。

提示词	必需参数	用途
research-discovery	topic	梳理术语、搜索、论文、研究集群和阅读路径
deep-paper-analysis	paper_id	深入分析一篇论文
summarize_paper	paper_id	总结方法、结果和局限性
compare_papers	paper_ids	比较多篇论文
literature_review	topic	综合某个主题及可选的论文集
literature-synthesis	paper_ids	综合多篇论文中的主题、方法、时间线或研究空白
research-question	paper_ids、topic	提出有依据且可证伪的研究问题

Streamable HTTP

适用于不便使用 stdio 的部署：

TRANSPORT=http HOST=127.0.0.1 PORT=8080 \
  uvx arxiv-mcp-server --storage-path /absolute/path/to/papers

PowerShell：

$env:TRANSPORT = "http"
$env:HOST = "127.0.0.1"
$env:PORT = "8080"
uvx arxiv-mcp-server --storage-path C:\absolute\path\to\papers

将客户端连接到：

{
  "mcpServers": {
    "arxiv": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

云端和负载均衡器探针应对 http://<host>:<port>/healthz 发送 GET 请求。HTTP 服务开始监听后，该端点会返回 200，响应正文为 ok。没有单独的 /ready 检查：进程运行即表示已就绪。stdio 传输没有 HTTP 端点。

该服务默认绑定到 127.0.0.1，并启用 MCP DNS 重绑定保护。如果反向代理对外暴露该服务，请让进程运行在私有接口上，并在上游配置身份验证和网络控制。使用 ALLOWED_HOSTS 和 ALLOWED_ORIGINS 设置代理转发的主机和来源值。

配置

设置项	默认值	用途
--storage-path	~/.arxiv-mcp-server/papers	论文、源缓存、提醒和索引的存储路径
MAX_RESULTS	50	服务端对结果数量的上限
ARXIV_REQUEST_TIMEOUT	30	所有 arXiv 请求（API、HTML、PDF、LaTeX）每次尝试的读取超时时间，单位为秒。值 ≤ 0 时使用默认值。
REQUEST_TIMEOUT	–	已弃用。 ARXIV_REQUEST_TIMEOUT 的旧别名（适用于所有请求）。仅在未设置 ARXIV_REQUEST_TIMEOUT 时使用。有效默认值：30s。值 ≤ 0 时使用默认值。
ARXIV_CONNECT_TIMEOUT	10	所有 arXiv 请求的连接超时时间，单位为秒。值 ≤ 0 时使用默认值。
ARXIV_MAX_TOTAL_TIME	50	每次工具调用的总时间预算，单位为秒（download_paper 的 HTML + PDF 合计）。值 ≤ 0 时使用默认值。注意：由于进程级限速器会延迟 3s，过小的预算（低于约 6s）可能无法为 HTML 转 PDF 回退留出足够时间。
ARXIV_MAX_RETRIES	2	瞬时故障（超时、连接错误、429、503）的最大重试次数
ARXIV_HTTP_406_MAX_RETRIES	1	HTTP 406 的最大重试次数（IP 级限流，请尽量减少重试）
ARXIV_INITIAL_BACKOFF	2.0	指数退避的初始延迟，单位为秒
ARXIV_MAX_BACKOFF	30	最大退避延迟，单位为秒（Retry-After 可以超过此值，并会导致立即返回 rate_limited）。值 ≤ 0 时使用默认值。
TRANSPORT	stdio	stdio、http 或 streamable-http
HOST	127.0.0.1	HTTP 绑定主机
PORT	8000	HTTP 绑定端口
ALLOWED_HOSTS	empty	额外接受的 HTTP Host 值
ALLOWED_ORIGINS	empty	额外接受的 HTTP Origin 值
SEMANTIC_SCHOLAR_API_KEY	empty	用于 citation_graph 的免费 Semantic Scholar API 密钥。可前往 https://www.semanticscholar.org/product/api#api-key 获取，以避免触发速率限制。未认证的请求在配额耗尽前也可使用。

通过 Pydantic 设置，环境变量名称不区分大小写。--storage-path 是命令行选项，而非环境设置。

安全

论文文本和 LaTeX 都是不可信的外部内容。论文中可能包含旨在诱使 AI 客户端忽略自身指令或调用无关工具的文本。

• 不要将论文中的指令视为可信命令。
• 对 shell、浏览器、文件系统和消息工具使用客户端审批控制。
• 在采取外部操作前，先检查生成的摘要。
• 除非上游提供了身份验证，否则请勿将 Streamable HTTP 暴露给外部。

报告政策和威胁详情请参阅 SECURITY.md。

开发

git clone https://github.com/blazickjp/arxiv-mcp-server.git
cd arxiv-mcp-server
uv sync --extra test --extra dev
uv run pytest
uv run black --check .

通过 MCP 客户端运行开发检出版本：

{
  "mcpServers": {
    "arxiv-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxiv-mcp-server",
        "run",
        "arxiv-mcp-server"
      ]
    }
  }
}

欢迎贡献。在提交拉取请求前，请阅读 CONTRIBUTING.md；如需报告可复现的错误或提出范围明确的功能建议，请使用 GitHub Issues。

许可证

Apache License 2.0。请参阅 LICENSE。