ScanSci PDF

ScanSci PDF 是一个面向研究者和学生的论文 PDF 下载工具。给它 DOI、arXiv ID 或论文列表，它会自动尝试开放获取、出版商接口、机构访问和浏览器登录等路径，尽量把可合法访问的全文 PDF 保存到本地。

它适合这些场景：

• 下载单篇论文或批量 DOI 列表
• 搜索论文并获取 DOI、BibTeX、RIS、EndNote 引文
• 用学校账号、WebVPN、CARSI、EZProxy 或浏览器 SSO 访问订阅论文
• 为 Elsevier / ScienceDirect 配置 API Key，快速获取全文 PDF
• 在 Agent / MCP 客户端中把论文下载能力交给 AI 助手调用

使用任何来源下载论文时，请遵守你所在机构、出版商和当地法律法规的授权范围。

快速开始

1. 安装

pip install scansci-pdf

如果你需要学校登录、WebVPN/CARSI/EZProxy、Cloudflare 页面处理或可见浏览器下载，安装完整功能：

pip install "scansci-pdf[cloakbrowser,instsci]"

2. 检查环境

scansci-pdf check

3. 下载第一篇论文

scansci-pdf get 10.1038/nature12373

默认输出目录是：

~/.scansci-pdf/papers

指定输出目录：

scansci-pdf get 10.1038/nature12373 --output downloads

4. 批量下载

准备一个文本文件 dois.txt，每行一个 DOI 或 DOI URL：

10.1038/nature12373
10.1016/j.neunet.2026.108582
https://doi.org/10.1126/science.aec6396

然后运行：

scansci-pdf batch dois.txt --output downloads

推荐配置：Elsevier / ScienceDirect API

如果你经常下载 Elsevier、ScienceDirect 或 Cell Press 的论文，建议首先配置 Elsevier API Key。配置后，ScanSci PDF 会优先使用官方 API：

Article Retrieval API ?view=FULL
  -> 获取全文 XML
  -> 解析 PDF attachment-eid
  -> Content Object API /content/object/eid/{eid}
  -> 下载出版社正式 PDF

这条路径绕过 ScienceDirect 网页、Cloudflare 和验证码，但闭源全文仍取决于你的机构订阅和请求 IP 是否有授权。

申请 API Key

1. 打开 https://dev.elsevier.com/
2. 注册或登录 Elsevier 账号。
3. 进入 My API Key / API Key Settings。
4. 创建 API Key；如果页面要求选择产品/API，选择 ScienceDirect / Article Retrieval 相关权限。
5. 复制 API Key，不要把它写进公开文档、日志或仓库。

保存到 ScanSci PDF

scansci-pdf elsevier-setup --api-key YOUR_KEY

如果你的图书馆明确提供 Elsevier institutional token，可以一并配置：

scansci-pdf elsevier-setup --api-key YOUR_KEY --inst-token YOUR_TOKEN

多数用户不需要 institutional token。校园网、学校 VPN、规则 VPN 或图书馆出口 IP 已经可能提供授权。若你配置了普通代理，请确认它没有覆盖 api.elsevier.com 的机构出口；ScanSci PDF 会对 Elsevier API 优先走 direct route，再回退到配置代理。配置后，可以下载一篇 Elsevier 论文确认是否已获得全文授权。

更详细的路径说明和排查方法见 Elsevier API 全文 PDF 稳定路径。

需要机构权限的论文

如果一篇论文不是开放获取，但你有学校或机构账号，可以使用以下方式。

统一浏览器登录

适合大多数出版商。工具会打开论文页面，你在浏览器里完成机构登录，之后 cookie 会保存复用。

scansci-pdf login --url https://www.sciencedirect.com/
scansci-pdf get 10.1016/j.neunet.2026.108582

WebVPN

适合学校提供 WebVPN 的情况。

scansci-pdf schools 北京
scansci-pdf setup 北京大学
scansci-pdf fetch 10.1016/j.neunet.2026.108582 --format markdown

CARSI / OpenAthens / Shibboleth

适合出版商页面提供 Access through your institution、Institutional Login、OpenAthens 或 Shibboleth 的情况。

scansci-pdf federated-login sciencedirect
scansci-pdf get 10.1016/j.neunet.2026.108582

登录、验证码、二次验证和机构密码都由用户在可见浏览器中完成，ScanSci PDF 不读取或保存你的密码。

常用命令

修改配置示例：

scansci-pdf config-cmd output_dir D:/papers
scansci-pdf config-cmd network_proxy socks5://127.0.0.1:1080

在 AI Agent / MCP 中使用

ScanSci PDF 也可以作为 MCP 服务运行，让支持 MCP 的 Agent 直接调用论文搜索、下载和引文工具。

stdio 模式

在 Claude Desktop、Cursor、Windsurf、Cline 等 MCP 客户端中添加：

{
  "mcpServers": {
    "scansci-pdf": {
      "command": "scansci-pdf",
      "args": ["run"]
    }
  }
}

HTTP 模式

适合远程部署或 Web 调用：

scansci-pdf run --mode streamable_http --host 0.0.0.0 --port 8000

常用 MCP 工具：

配置参考

查看全部配置：

scansci-pdf config-cmd

可选高级功能

Web UI

scansci-pdf web --port 8080

浏览器打开：

http://localhost:8080

Docker

适合长期运行服务或远程 MCP。

docker compose up -d

Tor

如果你的网络无法访问某些来源，可以配置代理或使用 Tor。Docker 模式会提供 Tor 服务；本地模式可按诊断提示启用。

CloakBrowser

遇到 Cloudflare、CAPTCHA、SSO 或出版商浏览器下载时，安装可选浏览器依赖：

pip install "scansci-pdf[cloakbrowser]"
scansci-pdf browser-doctor

CloakBrowser 是反爬检测对抗库，指纹补丁和检测规则更新频繁。如果以前能下载的站点突然开始被 Cloudflare/CAPTCHA 拦截、出现 403 或空响应，大概率是本地 cloakbrowser 版本过期，建议定期升级：

pip install -U cloakbrowser

可以用以下任一命令检查当前版本是否过旧（离线比对，不会联网上报）：

scansci-pdf doctor          # 表格中 package: cloakbrowser 行，过旧会标黄
scansci-pdf browser-doctor  # JSON 中 cloakbrowser_version.status = outdated

故障排查

下载失败

先运行：

scansci-pdf check

如果你在 MCP 里使用：

scansci_pdf_network_diagnose

Elsevier 返回 NOT_ENTITLED

常见原因是当前请求没有走机构出口。请检查：

• 是否已经连接校园网、学校 VPN 或规则 VPN
• api.elsevier.com 是否被普通代理转发到非机构 IP
• 学校是否订阅了目标期刊和年份

WebVPN 或机构登录失败

• 确认安装了完整依赖：pip install "scansci-pdf[cloakbrowser,instsci]"
• 在可见浏览器中完成登录、验证码或二次验证
• 登录后重新运行下载命令

浏览器下载以前能用，现在被拦

出版商和 Cloudflare 会持续更新反爬检测，cloakbrowser 也需要跟着升级来应对。如果以前能正常下载的出版商站点突然返回 403、长时间空白、跳到 CAPTCHA 或 Cloudflare 验证页，先检查 cloakbrowser 是否过旧：

scansci-pdf doctor

如果 package: cloakbrowser 标黄并提示 outdated，升级即可：

pip install -U cloakbrowser

下载速度慢

• 配置 Elsevier API Key 可显著改善 ScienceDirect 论文下载速度
• 批量任务可调整 batch_workers
• 网络受限时配置 network_proxy

交流群 / Community

扫码加入微信交流群，一起聊 AI for Science —— 偏 AI 应用与科研工具，也欢迎讨论 ScanSci PDF 的用法、bug 和需求。

微信群 / WeChat Group

群聊方向 AI 在科研场景的落地与工具链 论文检索、下载、阅读、整理的工作流 ScanSci PDF 使用问题与改进建议 二维码过期会更新，若扫码失效请在 issue 区留言。

更偏好异步交流？欢迎直接在 Issues 或 Discussions 区开贴。

更多资料

• Elsevier API 全文 PDF 稳定路径
• Elsevier API 成功经验：迁移到 InstSci
• 10 篇 Elsevier 闭源文章实测记录

开发者说明

本项目可作为 Python 包、CLI、Web UI 或 MCP 服务使用。核心下载流程会按来源健康度、响应速度和历史成功率动态排序，并在开放获取、出版商接口、机构访问和浏览器流程之间回退。

从 GitHub 克隆的用户使用纯 Python 实现；从 PyPI 安装的用户可能获得预编译扩展以提升性能。

赞助者

致谢

本项目在开发过程中参考和借鉴了以下开源项目：

• FlareSolverr - 早期反 bot 绕过架构设计
• CloakBrowser - Chromium stealth 浏览器
• ref-downloader - Publisher 专用下载策略参考
• paper-fetch-skill - 论文获取 Agent Skill 设计
• paper-fetcher - 论文下载流程参考

感谢以上项目作者的开源贡献。

许可证

Apache License 2.0

例外：src/scansci_pdf/_core/ 中的 Cython 编译扩展（.pyd/.so）为预编译二进制，仅通过 PyPI 分发。其 Cython 源码（.pyx）为专有代码，不包含在本仓库中。