Arxiv For Agents

arXiv 命令行界面 (CLI) 与 MCP 服务器

一个用于从arXiv.org搜索和下载论文的Python工具包，同时提供命令行界面和模型上下文协议（MCP）服务器，以支持大型语言模型（LLM）的集成。

CLI代理与文档齐全的CLI工具和/或MCP服务器配合良好。本项目提供了这两种选择。

特点/特性

• 搜索 按标题、作者、摘要、类别等搜索arXiv论文
• 下载 PDF文件自动进行本地缓存
• MCP服务器 用于与大型语言模型助手（如Claude Desktop等）集成
• 打字回复 使用 Pydantic 模型进行整洁的数据处理
• 速率限制 内置以遵循arXiv API指南
• 综合测试 包含26个集成测试（无模拟）

安装

选项1：从GitHub安装（推荐）

直接从GitHub仓库安装：

# Install the latest version
uv pip install git+https://github.com/LiamConnell/arxiv_for_agents.git

# Or with pip
pip install git+https://github.com/LiamConnell/arxiv_for_agents.git

# Now you can use the arxiv command
arxiv --help

选项2：从源代码安装

克隆仓库并在本地安装：

# Clone the repository
git clone https://github.com/LiamConnell/arxiv_for_agents.git
cd arxiv_for_agents

# Install in editable mode
uv pip install -e .

# Now you can use the arxiv command
arxiv --help

选项3：开发安装

对于包含所有依赖项的开发：

# Clone and install with dev dependencies
git clone https://github.com/LiamConnell/arxiv_for_agents.git
cd arxiv_for_agents
uv pip install -e ".[dev]"

# Run tests
uv run pytest

验证安装

# If installed as package
arxiv --help

# Or if using as module
uv run python -m arxiv --help

使用方法

注： 如果你是以包的形式安装的，请使用 arxiv 直接。否则，使用 uv run python -m arxiv。

搜索论文

按标题搜索：

# Using installed package
arxiv search "ti:attention is all you need"

# Or using as module
uv run python -m arxiv search "ti:attention is all you need"

按作者搜索：

arxiv search "au:Hinton" --max-results 20

按类别搜索：

arxiv search "cat:cs.AI" --max-results 10

组合搜索：

arxiv search "ti:transformer AND au:Vaswani"

获取特定论文

获取论文元数据并下载PDF：

arxiv get 1706.03762

仅获取元数据（不下载）：

arxiv get 1706.03762 --no-download

强制重新下载：

arxiv get 1706.03762 --force

下载PDF文件

仅下载PDF文件：

arxiv download 1706.03762

下载的PDF文件列表

arxiv list-downloads

JSON 输出

以JSON格式获取结果用于脚本编写：

arxiv search "ti:neural" --json
arxiv get 1706.03762 --json --no-download

搜索查询语法

arXiv API支持特定领域的搜索：

• ti: - 标题
• au: 作者
• abs: - 摘要
• cat: - 类别（例如，cs.AI，cs.LG）
• all: - 所有字段（默认）

你可以将搜索与 AND， OR，以及 ANDNOT：

arxiv search "ti:neural AND cat:cs.LG"
arxiv search "au:Hinton OR au:Bengio"

下载目录

PDF文件被下载到 ./.arxiv 默认情况下。使用以下方法更改此设置：

arxiv --download-dir ./papers search "ti:transformer"

MCP服务器（模型上下文协议）

arXiv 命令行界面（CLI）包含一个模型上下文协议（MCP）服务器，该服务器允许大型语言模型（LLM）助手（如 Claude Desktop）以编程方式搜索和下载 arXiv 论文。

运行MCP服务器

# Option 1: Using the script entry point (recommended)
uv run arxiv-mcp

# Option 2: Using the module
uv run python -m arxiv.mcp

服务器以标准输入输出模式运行，并通过stdin/stdout使用JSON-RPC进行通信。

MCP 工具

该服务器提供了4种用于论文发现和管理的工具：

1. 搜索论文 - 使用高级查询语法搜索arXiv

- 支持字段前缀（ti:、au:、abs:、cat:） - 布尔运算符（与、或、非） - 分页和排序选项 - 返回包含标题、作者、摘要、类别的论文元数据

1. 获取论文 - 获取特定论文的详细信息

- 接受灵活的ID格式（1706.03762，arXiv:1706.03762，1706.03762v1） - 可选地自动下载PDF文件 - 返回完整的元数据，包括DOI、期刊引用和评论

1. 下载论文 - 下载特定论文的PDF文件

- 下载到本地 .arxiv 目录 - 返回文件路径和大小信息 - 支持强制重新下载选项

1. 已下载论文列表 - 列出所有本地下载的PDF文件

- 显示arXiv ID、文件大小和路径 - 有助于管理本地废纸回收

MCP资源公司

服务器提供了2个资源供直接访问：

• 论文链接：//{arxiv_id}（注：此处的“arxiv_id”应替换为实际的ArXiv论文ID，以形成完整的论文链接） - 获取格式化的论文元数据（以Markdown格式）
• 下载://列表 - 获取所有已下载论文的Markdown表格

MCP 提示/指令

预置的提示模板以指导使用：

• 搜索arXiv提示 - 搜索arXiv论文指南
• 下载论文提示 - 论文下载与管理指南

克劳德桌面配置

添加到您的Claude Desktop配置文件中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

如果通过GitHub/pip安装：

{
  "mcpServers": {
    "arxiv": {
      "command": "arxiv-mcp"
    }
  }
}

如果从源代码/开发环境中运行：

{
  "mcpServers": {
    "arxiv": {
      "command": "uv",
      "args": ["run", "arxiv-mcp"],
      "cwd": "/path/to/arxiv_for_agents"
    }
  }
}

或者使用 --directory 以避免需要 cwd:

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

MCP（可能指某种特定系统、平台或协议的缩写，具体含义需根据上下文确定）用例

配置完成后，您可以要求Claude：

• “在arXiv上搜索关于Transformer架构的最新论文”
• “查找Geoffrey Hinton在cs.AI（人工智能计算机科学领域）类别下的论文”
• “下载《Attention is All You Need》论文”
• “给我看看2023年的神经网络相关论文”
• “列出我下载过的所有论文”
• “获取arXiv:1706.03762的摘要”

MCP（可能是指某种机器学习或计算平台）的集成使Claude能够自主地从arXiv上搜索、检索和管理学术论文。

建筑学

模块结构

arxiv/
├── __init__.py       # Package exports
├── __main__.py       # CLI entry point
├── cli.py            # Click commands
├── models.py         # Pydantic models
├── services.py       # API client service
└── mcp/              # MCP server
    ├── __init__.py   # MCP package exports
    ├── __main__.py   # MCP server entry point
    └── server.py     # FastMCP server with tools, resources, prompts

tests/
└── test_services.py  # Integration tests (26 tests)

Pydantic 模型

所有API响应均使用Pydantic进行类型标注：

from arxiv import ArxivService

service = ArxivService()
result = service.search("ti:neural", max_results=5)

# result is typed as ArxivSearchResult
print(f"Total: {result.total_results}")

for entry in result.entries:
    # entry is typed as ArxivEntry
    print(f"{entry.arxiv_id}: {entry.title}")
    print(f"Authors: {', '.join(a.name for a in entry.authors)}")

关键模型

• Arxiv搜索结果带有元数据的搜索结果

- total_results总匹配论文数 - entriesArxivEntry对象列表

• Arxiv条目个人论文

- arxiv_id清洁ID（例如，“1706.03762”） - title， summary论文元数据 - authors作者对象列表 - categories主题类别 - pdf_url直接PDF链接 - published， updated日期时间对象

• 作者论文作者

- name作者姓名 - affiliation可选隶属关系

测试

运行全部26个集成测试（会进行实际的API调用）：

uv run pytest tests/test_services.py -v

运行特定测试类：

uv run pytest tests/test_services.py::TestArxivServiceSearch -v

这些测试是集成测试，它们会调用真实的arXiv API，以确保服务能够与实际数据正常工作。

API限流

该服务默认在API请求之间强制执行3秒延迟（arXiv的建议）。您可以进行调整：

from arxiv import ArxivService

service = ArxivService(rate_limit_delay=5.0)  # 5 seconds

示例

Python API

from arxiv import ArxivService

# Initialize service
service = ArxivService(download_dir="./papers")

# Search
results = service.search(
    query="ti:attention is all you need",
    max_results=5,
    sort_by="relevance"
)

print(f"Found {results.total_results} papers")
for entry in results.entries:
    print(f"- {entry.title}")

# Get specific paper
entry = service.get("1706.03762", download_pdf=True)
print(f"Downloaded: {entry.title}")

# Just download PDF
pdf_path = service.download_pdf("1706.03762")
print(f"PDF saved to: {pdf_path}")

CLI 示例

# Find recent papers in a category
arxiv search "cat:cs.AI" \
  --max-results 10 \
  --sort-by submittedDate \
  --sort-order descending

# Search and output as JSON for processing
arxiv search "ti:transformer" --json | jq '.entries[].title'

# Batch download multiple papers
for id in 1706.03762 1810.04805 2010.11929; do
  arxiv download $id
done

发展

代码库遵循以下原则：

1. 类型安全所有API响应的Pydantic模型
2. 整洁架构（或：清洁架构）命令行界面（CLI）、服务和模型的分离
3. 实际测试使用实际API调用进行集成测试（不使用模拟）
4. 速率限制遵循arXiv API指南
5. 缓存自动本地缓存以避免重新下载

arXiv API 参考文档

• 基本URL：https://export.arxiv.org/api/query
• 格式：Atom XML
• 速率限制：请求之间间隔3秒（建议）
• 文档：https://info.arxiv.org/help/api/user-manual.html

许可证

这是一个用于与arXiv公开API交互的个人项目。