PaperPilot

学术论文全文获取工具 —— CLI 命令行工具 + Claude Code MCP Server

给一个 DOI 或关键词，PaperPilot 帮你搜论文、拉全文、下 PDF。注册为 Claude Code 的 MCP Server 后，直接用自然语言让 AI 帮你做文献调研。

工作原理

PaperPilot 采用四层递进策略，最大化获取论文全文的成功率：

第一层  Open Access        Unpaywall + arXiv           免费，无需登录
第二层  机构代理            WebVPN（国内）/ EZproxy      需要校园身份认证
第三层  直接出版商下载      已知 PDF URL 模式（Springer 等） 复用 Session cookie
第四层  元数据兜底          Semantic Scholar + OpenAlex  始终可用

每次请求先尝试 OA 开放获取（支持 SSL 自动降级）；若论文在付费墙内，自动走机构代理；代理失败后，尝试直接从出版商构造 PDF URL 下载（复用持久 Session 的 cookie）；实在拿不到全文，也会从 Semantic Scholar 和 OpenAlex 补全标题、作者、摘要等元数据。

核心特性

MCP Server —— 注册到 Claude Code，用自然语言搜论文、拉全文、查期刊分区
四层获取 —— OA 免费层 → 机构代理层 → 直接出版商下载 → 元数据兜底，逐层递进
SSL 容错 —— 校园网 SSL 劫持环境下自动降级（Unpaywall、DOI 解析、OA 下载均支持），可一键 --ssl-verify false 全局关闭验证
持久 Session —— 批量下载复用同一个 HTTP Session，Springer idp 认证只做一次，后续论文自动复用 cookie
双搜索引擎 —— Semantic Scholar + OpenAlex（2.5 亿+ 论文），默认双源搜索去重（DOI + 标题双重去重），支持关键词 / 语义 / 精确搜索，可按期刊名 / 文献类型过滤，自动分页突破单次请求上限（S2 最高 1000 条，OpenAlex 最高 10000 条）
HuggingFace Daily Papers —— 浏览 HuggingFace 每日推荐和热门论文，含 upvotes、GitHub 链接/Stars、AI 摘要等信息，支持导出和通过 arXiv 下载全文
IEEE Xplore 搜索 —— 支持通过机构代理搜索 IEEE Xplore 数据库，search --fetch 可直接批量下载 IEEE 搜索结果的 PDF（自动传递 article_number）
搜索结果导出 —— 支持导出为 Markdown（表格+摘要详情）、CSV（Excel 兼容）、JSON 三种格式
批量下载增强 —— 支持 --resume 断点续传（自动跳过已完成 DOI），--retry-failed 仅重试失败项（永久性失败自动跳过），--export 导出批量下载汇总，支持 .json bibliography 输入和 --type/--year-from/--year-to 过滤，Session 韧性机制（probe 检测 + anti-bot cooldown + 自动恢复），完成后显示耗时统计和错误分类
多出版商适配 —— Springer（文章+书章+会议论文）、Nature、Elsevier、Wiley、ACS、IEEE Xplore、ACM、Oxford Academic、IET、MIT Press 等专用提取器
反 Bot 绕过 —— 针对 Cloudflare WAF、JS 渲染页面等（IEEE、Elsevier、Oxford、Springer），自动回退到 headless 浏览器下载 PDF
期刊分区查询 —— 集成 easyScholar，自动显示中科院分区、JCR、IF、CCF 等级
双代理模式 —— 国内高校用 WRD WebVPN（网瑞达），海外高校用 EZproxy
校园网适配 —— SSL 劫持环境下的 DOI 解析、Unpaywall、OA 下载均自动降级，支持 --ssl-verify false 全局关闭
智能文件命名 —— PDF 保存为 {年份}_{完整标题}.pdf，无法下载时保存 _metadata.md
本地缓存 —— 自动缓存已获取的论文，避免重复请求
命令行工具 —— 支持单篇获取、批量获取、搜索等操作

安装

git clone https://github.com/Zhiqi123/Paper_Pilot.git
cd paper-pilot
pip install -e .

快速开始

1. 基础配置

# 设置邮箱（Unpaywall OA 检测需要）
paper-pilot config-cmd --email your@email.com

# 可选：设置 OpenAlex API key（$1/天免费额度，用于论文搜索）
paper-pilot config-cmd --openalex-api-key YOUR_KEY

# 可选：设置 easyScholar key（用于期刊分区查询）
paper-pilot config-cmd --easyscholar-key YOUR_KEY

# 可选：校园网 SSL 劫持环境下关闭 SSL 验证
paper-pilot config-cmd --ssl-verify false

2. 配置机构代理（可选，获取付费论文需要）

国内高校（WebVPN）

大多数国内高校使用 WRD（网瑞达）WebVPN 系统。

# 设置 WebVPN 主机名（以集美大学为例）
paper-pilot config-cmd --webvpn-host webvpn.jmu.edu.cn

# 登录（打开浏览器完成统一身份认证）
paper-pilot login

少数学校使用了自定义 AES key（默认是 wrdvpnisthebest!）：

paper-pilot config-cmd --webvpn-key "YourCustomKey1234"

海外高校（EZproxy）

paper-pilot config-cmd --proxy-type ezproxy
# 然后编辑 ~/.paper-pilot/config.json 修改 proxy_base

不使用代理

仅用 OA 和 Metadata 层：

paper-pilot config-cmd --proxy-type none

3. 注册 MCP Server（与 Claude Code 集成）

# 全局注册（推荐，在任何项目目录下都可使用）
claude mcp add paper-pilot --scope user -- paper-pilot-mcp

# 或：仅当前项目注册（只在 paper-pilot 项目目录下可用）
claude mcp add paper-pilot -- paper-pilot-mcp

--scope user vs 默认（project）： 不加 --scope 时，MCP Server 只注册到当前项目的 local config，换一个目录就看不到了。加 --scope user 会写入 ~/.claude.json，全局可用。

注册后重启 Claude Code 会话（退出再进入），即可在工具列表中看到 paper-pilot 的 5 个工具。

验证注册是否成功：

claude mcp list

如果输出中没有 paper-pilot，检查以下几点：

确认 paper-pilot-mcp 命令可执行：which paper-pilot-mcp
确认注册到了正确的 scope：查看 ~/.claude.json 中是否有 paper-pilot 条目
如果之前用默认 scope 注册过，在其他项目目录下不可见，需重新用 --scope user 注册

重启后，直接对话即可：

"帮我搜几篇关于钙钛矿太阳能电池的最新论文"

"把 DOI 10.1038/s41566-024-01234-5 的全文拉下来"

"查一下 Nature Energy 的期刊分区"

命令行用法

搜索论文

paper-pilot search QUERY [OPTIONS]

选项	简写	默认值	说明
`--limit`	`-n`	`10`	最大结果数（S2 上限 1000，OpenAlex 上限 10000，自动分页）
`--year`	`-y`		年份范围，如 `2020-2024` 或 `2020-`
`--source`	`-s`	`all`	搜索源：`s2`（Semantic Scholar）、`openalex`、`ieee`、`all`（双源去重）
`--mode`	`-m`	`keyword`	OpenAlex 搜索模式：`keyword`、`semantic`、`exact`
`--sort`			排序：`cited_by_count:desc`、`publication_date:desc`
`--oa`		`false`	仅返回开放获取论文
`--type`	`-T`		OpenAlex 文献类型过滤：`article`、`book`、`book-chapter`、`book\|book-chapter`
`--journal`	`-j`		按期刊名过滤（OpenAlex 原生过滤，S2 后过滤）
`--source-id`			OpenAlex 源 ID 过滤（如 `https://openalex.org/S19605986`）
`--fetch`		`false`	同时获取每篇论文的全文
`--export`	`-e`		导出结果到文件（支持 `.md`、`.csv`、`.json`）
`--verbose`	`-v`	`false`	显示详细日志

# 基础搜索（默认双源：Semantic Scholar + OpenAlex）
paper-pilot search "organic photovoltaics stability"

# 指定年份范围，增加结果数
paper-pilot search "perovskite solar cells" -n 50 --year 2022-2025

# 使用 OpenAlex 语义搜索
paper-pilot search "fuzzy neural network" --source openalex --mode semantic

# 按引用量排序，仅看 OA 论文
paper-pilot search "fuzzy" --source openalex --year 2020-2025 --sort cited_by_count:desc --oa

# 仅搜索书籍和书章
paper-pilot search "machine learning" --type "book|book-chapter"

# 按期刊名过滤（OpenAlex 原生过滤）
paper-pilot search "solar cells" --journal "Nature Energy" --source openalex

# 搜完直接拉全文
paper-pilot search "silver nanowire transparent electrode" -n 20 --fetch

# 大批量搜索并导出为 Markdown（含表格 + 每篇摘要详情）
paper-pilot search "perovskite solar cells" -n 200 --source openalex --export results.md

# 导出为 CSV（方便 Excel 分析）
paper-pilot search "neural network" -n 50 --export results.csv

# 导出为 JSON（程序化处理）
paper-pilot search "machine learning" -n 30 --export results.json

# 通过 OpenAlex source_id 精确定位期刊
paper-pilot search "music" --source openalex --source-id "https://openalex.org/S19605986" -n 10

# 搜索 IEEE Xplore（需机构代理）
paper-pilot search "speech recognition" --source ieee -n 20

# 搜索 IEEE 并直接下载所有结果的 PDF
paper-pilot search "music emotion recognition" --source ieee -n 10 --fetch

浏览 HuggingFace Daily Papers

paper-pilot hf-daily [OPTIONS]

选项	简写	默认值	说明
`--trending`	`-t`	`false`	显示热门论文（按 upvotes 排序）而非每日推荐
`--date`	`-d`	今天	指定日期（YYYY-MM-DD）
`--limit`	`-n`	`50`	最大结果数
`--fetch`		`false`	通过 arXiv 下载全文
`--export`	`-e`		导出结果到文件（支持 `.md`、`.csv`、`.json`）
`--verbose`	`-v`	`false`	显示详细日志

# 查看今日推荐论文
paper-pilot hf-daily

# 查看热门论文
paper-pilot hf-daily --trending

# 查看指定日期的推荐
paper-pilot hf-daily --date 2026-03-10

# 导出为 Markdown（含标题、作者、摘要、GitHub 链接、upvotes 等）
paper-pilot hf-daily --export papers.md

# 导出热门论文并下载全文
paper-pilot hf-daily --trending -n 10 --export trending.md --fetch

导出字段： 标题、作者、年代、摘要、DOI、arXiv 链接、HuggingFace 链接、GitHub 链接/Stars、项目主页、组织、Upvotes、AI 摘要、关键词。

获取单篇论文

paper-pilot fetch IDENTIFIER [OPTIONS]

IDENTIFIER 支持 DOI、DOI URL（https://doi.org/...）或出版商 URL。

选项	简写	默认值	说明
`--format`	`-f`	`json`	输出格式：`json`、`markdown`、`text`
`--text-only`	`-t`	`false`	仅输出纯文本（最少 token，适合喂给 LLM）
`--output`	`-o`		自定义 PDF 输出目录
`--no-cache`		`false`	跳过本地缓存
`--verbose`	`-v`	`false`	显示详细日志

# 通过 DOI 获取
paper-pilot fetch "10.1038/s41566-024-01234-5"

# 通过出版商 URL 获取
paper-pilot fetch "https://www.nature.com/articles/s41566-024-01234-5"

# 输出 Markdown 格式
paper-pilot fetch "10.1038/s41566-024-01234-5" -f markdown

# 纯文本输出（方便管道传给 LLM）
paper-pilot fetch "10.1038/s41566-024-01234-5" -t

# 跳过缓存，指定输出目录
paper-pilot fetch "10.1109/TFUZZ.2008.2004990" --no-cache -o ./papers

输出文件：

有全文权限 → 保存 PDF，如 2024_Perovskite_Solar_Cells_A_Review.pdf
无全文权限 → 保存元数据文件，如 2024_Perovskite_Solar_Cells_A_Review_metadata.md（含标题、作者、期刊引用、DOI、摘要、期刊分区）

批量获取

paper-pilot batch FILE [OPTIONS]

FILE 支持 .txt 文本文件（每行一个 DOI，# 开头的行会被忽略）和 .json bibliography 文件。

选项	简写	默认值	说明
`--output`	`-o`		输出目录
`--format`	`-f`	`json`	输出格式：`json`、`markdown`、`text`
`--resume`	`-r`	`false`	断点续传，跳过已完成的 DOI
`--retry-failed`		`false`	仅重试之前失败的 DOI（永久性失败如 `no_access`/`not_found`/`denied` 不再重试）
`--export`	`-e`		完成后导出批量汇总（支持 `.md`、`.csv`、`.json`）
`--type`			按类型过滤：`journals`、`conferences`（需要 JSON 输入）
`--year-from`			按年份过滤：起始年份
`--year-to`			按年份过滤：截止年份
`--cooldown/--no-cooldown`		`true`	启用/禁用 anti-bot 周期性休眠
`--cooldown-every`		`30`	每 N 次成功后触发休眠（默认 30）
`--probe/--no-probe`		`true`	启用/禁用 session probe 健康检测
`--verbose`	`-v`	`false`	显示详细日志

# 基本批量下载（支持 .txt DOI 列表和 .json bibliography）
paper-pilot batch dois.txt --format markdown --output ./papers
paper-pilot batch bibliography.json

# 按类型过滤（需要 JSON 输入）
paper-pilot batch bibliography.json --type journals
paper-pilot batch bibliography.json --type conferences

# 按年份范围过滤
paper-pilot batch bibliography.json --year-from 2020
paper-pilot batch bibliography.json --year-from 2015 --year-to 2023

# 断点续传（中断后重新运行，自动跳过已完成的 DOI）
paper-pilot batch dois.txt --resume

# 仅重试之前失败的 DOI
paper-pilot batch dois.txt --retry-failed

# Session 韧性配置
paper-pilot batch dois.txt --no-cooldown              # 禁用 anti-bot cooldown
paper-pilot batch dois.txt --cooldown-every 50         # 每 50 次成功后休息
paper-pilot batch dois.txt --no-probe                  # 禁用 session probe 测试

# 批量下载并导出汇总报告
paper-pilot batch dois.txt --export summary.md

# 组合使用
paper-pilot batch bibliography.json --type journals --year-from 2020 --retry-failed
paper-pilot batch dois.txt --resume --export summary.csv --output ./papers

断点续传原理： 进度以 dict-based 格式保存在 {output_dir}/.batch_progress.json，记录每篇论文的详细状态（status/filename/size/error）。使用 --resume 时自动跳过已完成和永久失败的 DOI，新论文优先处理，暂时性失败排到队列末尾；--retry-failed 仅重试暂时性失败项（永久性失败如 no_access/not_found/denied 自动跳过）。旧版 set-based 格式会自动迁移（备份为 .json.bak）。全部完成后进度文件自动删除。批量完成后显示耗时统计（papers/hour）和错误分类。

Session 韧性： 批量下载过程中，SessionGuard 自动管理 session 健康：probe 测试定期检测 session 是否降级，cooldown 机制周期性休眠避免触发反爬，session 降级时自动重载 cookie 并恢复连接。MacBook 合盖/重开等网络中断场景下，probe 和恢复流程会渐进式等待网络恢复（30s → 120s），避免因 DNS 解析失败直接退出。

登录机构代理

paper-pilot login          # 检查并登录
paper-pilot login --force  # 强制重新登录

缓存管理

paper-pilot cache clear    # 清空所有缓存

环境诊断

paper-pilot doctor    # 检查配置、网络连通性、Chrome、SSL、代理状态

查看/修改配置

paper-pilot config-cmd                            # 查看当前配置
paper-pilot config-cmd --email your@email.com     # 设置邮箱
paper-pilot config-cmd --output-dir ./my-papers   # 设置输出目录

MCP Server 工具

注册为 MCP Server 后，Claude Code 会自动发现以下工具：

工具	说明
`fetch_paper`	通过 DOI 或 URL 获取论文全文，支持 `detail` 控制截断（默认 concise 截断到 16K 字符）、`sections` 选择性返回部分内容（如仅 metadata+abstract）
`search_papers`	搜索论文（默认双源：S2 + OpenAlex），支持年份、期刊名、模式、文献类型过滤，`detail=detailed` 返回完整摘要和额外字段
`get_paper_metadata`	通过 DOI 获取论文元数据（不下载全文，更轻量）
`get_journal_ranking`	查询期刊分区（中科院分区、JCR、IF、CCF 等级）
`browse_hf_daily`	浏览 HuggingFace 每日推荐/热门论文，`detail=detailed` 含 AI 摘要/关键词

所有工具均附带 ToolAnnotations（readOnlyHint=True, idempotentHint=True, openWorldHint=True），帮助 agent 在调用前了解工具行为。空结果和错误时返回 actionable 建议信息，引导 agent 调整查询策略。

MCP 工具参数说明

fetch_paper 新增参数：

参数	默认值	说明
`detail`	`"concise"`	`concise`：截断全文到 ~16K 字符；`full`：返回完整文本
`sections`	`""`	逗号分隔，可选 `metadata,abstract,full_text,figures,references`，覆盖 detail

# 示例：仅获取元数据和摘要（最小 token）
fetch_paper("10.1038/nphys1509", sections="metadata,abstract")

# 示例：获取完整全文
fetch_paper("10.1038/nphys1509", detail="full")

# 示例：arXiv 论文
fetch_paper("arxiv:2301.07041")

search_papers / browse_hf_daily 新增参数：

参数	默认值	说明
`detail`	`"concise"`	`concise`：简短摘要（200/300 字符）；`detailed`：完整摘要 + 额外字段

MCP Server 是什么？ MCP (Model Context Protocol) 是一个标准协议，让 AI 助手可以调用外部工具。PaperPilot 的 MCP Server 是一个独立进程，通过 stdio 与 Claude Code 通信，将 Python 函数暴露为 Claude 可直接调用的 tool。注册后无需额外配置插件或 Skill。

配置文件

配置存储在 ~/.paper-pilot/config.json：

字段	说明	默认值
`proxy_type`	代理类型：`webvpn` / `ezproxy` / `none`	`webvpn`
`webvpn_host`	WebVPN 主机名	`""`
`webvpn_key`	WebVPN AES 密钥	`wrdvpnisthebest!`
`proxy_base`	EZproxy 登录 URL	`http://eproxy.lib.hku.hk/login?url=`
`email`	Unpaywall API 邮箱	`""`
`s2_api_key`	Semantic Scholar API key（可选）	`""`
`openalex_api_key`	OpenAlex API key（可选）	`""`
`easyscholar_secret_key`	easyScholar 密钥（期刊分区查询）	`""`
`ssl_verify`	全局 SSL 验证开关（`false` 适合校园网）	`true`
`ssl_verify_fallback`	SSL 失败时自动降级为 `verify=False`	`true`
`output_dir`	PDF 输出目录	`~/.paper-pilot/papers`
`cache_dir`	缓存目录	`~/.paper-pilot/cache`
`request_delay_min`	请求最小间隔（秒）	`2.0`
`request_delay_max`	请求最大间隔（秒）	`5.0`

配置示例（国内高校）：

{
  "proxy_type": "webvpn",
  "webvpn_host": "webvpn.xmu.edu.cn",
  "email": "your@email.com",
  "openalex_api_key": "your-openalex-key",
  "easyscholar_secret_key": "your-easyscholar-key"
}

配置示例（海外高校）：

{
  "proxy_type": "ezproxy",
  "proxy_base": "http://your-institution-proxy.edu/login?url=",
  "email": "your@email.com"
}

项目结构

paper-pilot/
├── paper_pilot/
│   ├── cli.py                  # 命令行界面 (Typer)
│   ├── mcp_server.py           # MCP Server（5 个工具）
│   ├── fetcher.py              # 核心获取逻辑（四层策略 + 浏览器 fallback + 持久 Session）
│   ├── batch_progress.py       # 统一批量进度跟踪（dict-based 记录 + 自动迁移）
│   ├── session_guard.py        # Session 韧性（probe 测试 + cooldown + 自动恢复）
│   ├── browser_pdf.py          # Headless Chrome PDF 下载（反 Bot 绕过）
│   ├── auth.py                 # EZproxy 认证 (Selenium)
│   ├── webvpn_auth.py          # WebVPN 认证 (Selenium + CAS 统一身份认证)
│   ├── webvpn_url.py           # WebVPN URL 编解码 (AES-128-CFB)
│   ├── config.py               # 配置管理
│   ├── models.py               # Paper 数据模型
│   ├── sources/                # 数据源
│   │   ├── semantic_scholar.py # Semantic Scholar 搜索与元数据
│   │   ├── openalex.py         # OpenAlex 搜索（2.5 亿+ 论文）
│   │   ├── ieee_xplore.py      # IEEE Xplore 搜索（POST REST API）
│   │   ├── huggingface.py      # HuggingFace Daily Papers（每日推荐+热门）
│   │   ├── unpaywall.py        # Unpaywall OA 检测
│   │   ├── arxiv.py            # arXiv 元数据 + PDF 下载
│   │   └── easyscholar.py      # easyScholar 期刊分区查询
│   └── extractors/             # 内容提取
│       ├── html_extractor.py   # HTML 提取路由
│       ├── pdf_extractor.py    # PDF 文本提取 (pymupdf)
│       └── publisher_adapters/ # 出版商专用提取器
│           ├── springer.py    # Springer（文章+书章+会议论文）
│           ├── nature.py
│           ├── elsevier.py
│           ├── wiley.py
│           ├── acs.py
│           ├── ieee.py
│           ├── acm.py         # ACM Digital Library
│           ├── oup.py         # Oxford Academic
│           ├── iet.py         # IET Digital Library
│           ├── mit_press.py   # MIT Press
│           └── generic.py      # 通用回退
├── pyproject.toml
├── LICENSE
└── README.md

环境要求

Python >= 3.10
Chrome 浏览器（机构代理登录和浏览器 PDF 下载需要）

许可证

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

PaperPilot

工作原理

核心特性

安装

快速开始

1. 基础配置

2. 配置机构代理（可选，获取付费论文需要）

3. 注册 MCP Server（与 Claude Code 集成）

命令行用法

搜索论文

浏览 HuggingFace Daily Papers

获取单篇论文

批量获取

登录机构代理

缓存管理

环境诊断

查看/修改配置

MCP Server 工具

MCP 工具参数说明

配置文件

项目结构

环境要求

许可证

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
paper_pilot		paper_pilot
tests		tests
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

PaperPilot

工作原理

核心特性

安装

快速开始

1. 基础配置

2. 配置机构代理（可选，获取付费论文需要）

3. 注册 MCP Server（与 Claude Code 集成）

命令行用法

搜索论文

浏览 HuggingFace Daily Papers

获取单篇论文

批量获取

登录机构代理

缓存管理

环境诊断

查看/修改配置

MCP Server 工具

MCP 工具参数说明

配置文件

项目结构

环境要求

许可证

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages