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

打开 https://dev.elsevier.com/
注册或登录 Elsevier 账号。
进入 My API Key / API Key Settings。
创建 API Key；如果页面要求选择产品/API，选择 ScienceDirect / Article Retrieval 相关权限。
复制 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 check`
下载单篇论文	`scansci-pdf get DOI_OR_ARXIV`
下载并输出更详细结果	`scansci-pdf fetch DOI --format markdown`
批量下载 DOI 列表	`scansci-pdf batch dois.txt --output downloads`
搜索支持的学校	`scansci-pdf schools 清华`
配置学校 WebVPN	`scansci-pdf setup 学校名称`
浏览器登录出版商	`scansci-pdf login --url 出版商网址`
配置 Elsevier API	`scansci-pdf elsevier-setup --api-key YOUR_KEY`
查看或修改配置	`scansci-pdf config-cmd`
启动 Web UI	`scansci-pdf web --port 8080`
检查浏览器运行时	`scansci-pdf browser-doctor`

修改配置示例：

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_download`	下载单篇 DOI/arXiv
`scansci_pdf_batch_download`	批量下载
`scansci_pdf_search`	搜索论文
`scansci_pdf_citation`	获取 BibTeX/RIS/EndNote
`scansci_pdf_login`	打开浏览器完成机构登录
`scansci_pdf_elsevier_setup`	引导配置 Elsevier API Key
`scansci_pdf_network_diagnose`	网络诊断

配置参考

配置项	默认值	说明
`output_dir`	`~/.scansci-pdf/papers`	PDF 保存目录
`auto_rename`	`true`	自动按作者/标题重命名
`scihub_enabled`	`true`	启用 Sci-Hub/LibGen 类来源
`network_proxy`	空	HTTP/SOCKS 代理地址
`proxy_pool`	空	逗号分隔的代理列表；非空时批量下载按代理轮换出口 IP
`batch_workers`	`10`	批量下载并发数（被封 IP 时建议调低到 2）
`request_delay_min`	`2.0`	请求间随机延迟下限（秒）
`request_delay_max`	`5.0`	请求间随机延迟上限（秒）
`instsci_enabled`	`false`	启用 WebVPN
`instsci_school`	空	WebVPN 学校名称
`carsi_enabled`	`false`	启用 CARSI
`carsi_idp_name`	空	CARSI 机构名称
`elsevier_api_key`	空	Elsevier / ScienceDirect API Key
`elsevier_insttoken`	空	Elsevier institutional token，可选
`browser_headless`	`false`	浏览器是否无头运行
`browser_humanize`	`true`	浏览器人性化操作

查看全部配置：

scansci-pdf config-cmd

可选高级功能

Web UI

scansci-pdf web --port 8080

浏览器打开：

http://localhost:8080

Docker

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

docker compose up -d

服务	端口	说明
`scansci-pdf`	`8000`	streamable HTTP MCP 服务
`tor`	`1080`	Tor SOCKS5 代理

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

被 ACS 等出版商封 IP（IP Address Blocked）

批量下载 ACS（pubs.acs.org）等出版商时，可能遇到整页报错：

IP Address Blocked — Your IP address has been blocked automatically due to unusual behavior. Contact ipblock@acs.org.

这是出版商的自动反爬封锁。机构出口 IP（如校园网 166.111.x.x）是共享的，一个人触发就可能让整段 IP 被封，所以容易"经常有人遇到"。

立即解除（封禁在出版商侧，代码改不了）：

邮件 ipblock@acs.org 申诉，附上被封 IP，通常 1–3 个工作日解封
换出口 IP（代理 / 手机热点）可绕过，但会失去机构订阅授权，只能下 OA 论文
部分封锁会在 24–48 小时后自动解除

预防（降低被封概率）——让请求看起来像人在浏览，而不是 10 线程同时打：

scansci-pdf config-cmd batch_workers 2          # 调低并发（默认 10）
scansci-pdf config-cmd request_delay_min 5      # 拉大随机延迟下限（默认 2）
scansci-pdf config-cmd request_delay_max 12     # 拉大随机延迟上限（默认 5）

自动停损：从 v1.9.0 起，批量任务一旦连续 3 次检测到 IP 被封（ACS 封锁页 / HTTP 403 / 429），会自动取消剩余下载，避免越踩越深。无需配置，默认开启。触发时终端会显示：

⚠ 已自动停止：连续检测到 IP 被出版商封禁（N 篇返回 ip_blocked），剩余任务已取消。

代理池轮换（进阶）：如果有多个代理可用，可以配置代理池让批量下载轮换出口 IP，从源头降低单 IP 被盯上的概率：

scansci-pdf config --proxy-pool "socks5://1.1.1.1:1080,http://2.2.2.2:8080,socks5://3.3.3.3:1080"

启用后，每个代理启动一个独立浏览器上下文，记录按 round-robin 分配到各代理。某个代理连续被封（3 次）会被自动剔除，剩余记录转到其他代理；所有代理都被封才会整体停止。登录只需完成一次，cookies 会复用到各代理上下文。

⚠ 权衡：同一登录态从多个 IP 并发访问，少数出版商可能视为异常（账号共享/被盗）。这比被整体封 IP 更可接受，但如果你的机构对这种检测敏感，保持 proxy_pool 为空即可回到单上下文模式。

下载速度慢

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

交流群 / Community

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

_{微信群 / WeChat Group}

群聊方向

AI 在科研场景的落地与工具链
论文检索、下载、阅读、整理的工作流
ScanSci PDF 使用问题与改进建议

_{二维码过期会更新，若扫码失效请在 issue 区留言。}

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

开发者说明

本项目可作为 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）为专有代码，不包含在本仓库中。

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.claude/skills		.claude/skills
.codex		.codex
.github/workflows		.github/workflows
GrShaderCache		GrShaderCache
GraphiteDawnCache		GraphiteDawnCache
ShaderCache		ShaderCache
assets/brand		assets/brand
component_crx_cache		component_crx_cache
docs		docs
extensions_crx_cache		extensions_crx_cache
scripts		scripts
skill		skill
src/scansci_pdf		src/scansci_pdf
test_downloads		test_downloads
tests		tests
tor		tor
.dockerignore		.dockerignore
.gitignore		.gitignore
BrowserMetrics-spare.pma		BrowserMetrics-spare.pma
Dockerfile		Dockerfile
LICENSE		LICENSE
Last Browser		Last Browser
Last Version		Last Version
Local State		Local State
README.md		README.md
Variations		Variations
build_core.py		build_core.py
docker-compose.yml		docker-compose.yml
elsevier_10_closed_articles.md		elsevier_10_closed_articles.md
install.ps1		install.ps1
install.sh		install.sh
nature_10.txt		nature_10.txt
pyproject.toml		pyproject.toml
setup.py		setup.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation