Scholar MCP

Scholar MCP

学术论文、专利、书籍、标准及 PDF 转换

文档 | 配置向导 | PyPI | Docker

功能

29 个工具，按学术来源类型分类。

来源领域

• 论文：支持按年份、出版场所、领域和引用筛选的全文搜索；可通过 DOI、S2 ID、arXiv ID、ACM ID 或 PubMed ID 查询单篇论文；搜索作者资料和姓名；查找正向引用、反向参考文献，进行 BFS 图遍历和最短路径桥接发现；根据正面／负面示例获取推荐；生成 BibTeX/CSL-JSON/RIS 引文，并通过 OpenAlex 补充出版场所信息。
• 专利：通过 EPO OPS 搜索 100 多个专利局，并按 CPC、申请人、发明人和管辖区筛选；提供书目信息、权利要求、说明书、专利族、法律信息和引用等部分；通过 Semantic Scholar 将非专利文献解析为论文，并发现论文对专利的引用。EPO 凭据为可选项；其他领域无需凭据即可使用。
• 图书：通过 Open Library 按标题、作者和关键词搜索，无需 API 密钥；可通过 ISBN-10/13 或 Open Library 作品／版本 ID 查询；按主题获取并按受欢迎程度排序的推荐；Google Books 摘录和预览链接；用于查找图书馆资源的 WorldCat 永久链接；缓存封面图片。externalIds 中含 ISBN 的论文会自动从 Open Library 补充出版商、版本、封面 URL 和主题数据。
• 标准：解析标识符、搜索并检索 NIST、IETF、W3C 和 ETSI 标准的元数据；还可选择通过 docling 获取全文并转换为 Markdown。第二层级的 ISO、IEC、IEEE、Common Criteria (CC) 和 CEN/CENELEC 元数据（包括 ISO/IEC/IEEE 联合标准，以及 CC ↔ ISO/IEC 15408 交叉链接）通过 sync-standards 在本地同步。ISO、IEC 和 IEEE 在标识符未同步时会回退到实时获取；CC 和 CEN 没有实时 API，需先进行同步。符合标准模式的引文（RFC、ISO、NIST SP、IEEE、EN、CC）会自动补充结构化的 standard_metadata，其中包含标识符、标题、机构、状态，以及可用时的全文 URL（参见 docs/guides/standards.md）。

跨领域功能

• 信息补充流程：分阶段从多个来源补充信息：OpenAlex（开放获取状态、隶属机构、资助方、概念）、CrossRef（出版商、页码范围、容器标题）、Google Books（预览链接、摘录）和 Open Library（图书元数据）。对论文和图书搜索结果自动运行。
• PDF 转换：下载开放获取 PDF，并通过 docling-serve 转换为 Markdown；可选择通过 VLM 补充公式和图表信息；当 Semantic Scholar 没有开放获取链接时，自动回退到 ArXiv、PubMed Central 和 Unpaywall；还可直接下载在其他来源找到的 PDF URL；转换后的文本会分页，以便大型文档也能放入 MCP 响应中。
• 智能缓存：基于 SQLite 的缓存，按表设置 TTL（论文／作者为 30 天，引用／参考文献为 7 天），并支持标识符别名。
• 身份验证：可使用 bearer token、OIDC (OAuth 2.1)，或同时使用两者（多重身份验证）。
• 多传输方式：支持 stdio（Claude Desktop）、HTTP（streamable-http）和 SSE 传输方式。
• Linux 软件包：提供 .deb 和 .rpm 软件包，包含 systemd 服务和安全加固配置。

各领域覆盖情况

各领域的深度并不均衡。目前，论文拥有最丰富的工具功能（引用图谱、推荐，以及与其他三个领域的交叉引用）；标准领域的功能最精简。这反映的是公开数据的可用性，而非价值层级：撰写论文通常需要用到全部四种来源类型来查找引文和现有技术。功能对齐工作通过 GitHub issues 和 里程碑 跟踪；路线图展示的是计划方向，并不承诺功能完整性。

可以用它做什么

在 MCP 客户端（Claude 等）中挂载此服务后，你可以：

• 调研一个领域：“找出 2020 至 2024 年间图神经网络领域被引用次数最多的 20 篇论文，并拟定一份文献综述大纲。”组合使用 search_papers、get_citations 和 enrich_paper。
• 追溯引用路径：“从《Attention is All You Need》到《RLHF for dialogue agents》的最短引用路径是什么？”使用 find_bridge_papers 和 get_citation_graph。
• 交叉检索现有技术：“对于这个专利族，列出其引用的学术论文，以及描述中提及的任何书籍或标准。”组合使用 get_patent、batch_resolve 和标准／书籍补充信息。
• 生成参考文献：“使用 OpenAlex 的出版物信息，为这些 DOI 生成 BibTeX。”使用 generate_citations。
• 查询标准：“RFC 9000 的最新状态是什么？并获取 Markdown 完整文本。”使用 resolve_standard_identifier 和 get_standard。

安装

从 PyPI 安装

pip install pvliesdonk-scholar-mcp

如果你通过 pyproject.toml 中的 PROJECT-EXTRAS-START / PROJECT-EXTRAS-END 标记添加可选 extras，请在下方记录：

• [all]：一个 extra 包含所有生产功能；Linux 软件包和 Claude Desktop bundle 都会安装它。
• [debug]：添加远程调试器（debugpy）；参见远程调试。

基础软件包已通过 fastmcp-pvl-core 包含 FastMCP，因此只需运行 pip install pvliesdonk-scholar-mcp，即可使用 scholar-mcp serve。保留较早的 [mcp] extra 是为了继续支持现有安装命令；它不会在基础软件包之外添加任何内容。

从源代码安装

git clone https://github.com/pvliesdonk/scholar-mcp.git
cd scholar-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/scholar-mcp:latest

若要运行最新合并的代码，而不是最新发行版，请使用滚动更新的 edge 标签。每次合并到 main 后都会重新构建该标签，且不包含版本标识。完整标签列表请参见镜像标签。

docker pull ghcr.io/pvliesdonk/scholar-mcp:edge

仓库根目录附带一个 compose.yml，可直接运行：将 .env.example 复制为 .env，然后运行 docker compose up -d。它会在主机上发布端口 8000，且假定没有反向代理；Docker Compose 介绍了配置拆分、域名标记块和 Traefik 覆盖配置。

如需连接远程 Python 调试器（仅限开发；该协议未经身份验证），请参见远程调试。

Linux 软件包（.deb / .rpm）

从 GitHub Releases 页面下载 .deb 或 .rpm 软件包。两者都会安装经过安全加固的 systemd 单元；环境配置从 /etc/scholar-mcp/env 读取（可从随附的 /etc/scholar-mcp/env.example 复制）。

Claude Desktop（.mcpb bundle）

从 GitHub Releases 页面下载 .mcpb bundle，双击即可安装，也可以运行：

mcpb install scholar-mcp-<version>.mcpb

Claude Desktop 会通过图形界面向导提示输入所需的环境变量，无需手动编辑 JSON。

有关 Claude Desktop 的手动配置和设置选项，请参见 Claude Desktop 部署。

发布渠道

制品通过三个渠道发布。每一行都准确列出了该渠道发布的内容。

渠道	版本标识	制品
edge（滚动）	无；提交本身就是标识	Docker 镜像 :edge，每次合并到 main 时重新构建；.mcpb 捆绑包，作为 mcpb-bundle-edge 工作流制品；Claude Code 插件 .zip，作为 plugin-zip-edge 制品；滚动的 unstable 文档版本。不会留下 Git 标签、GitHub 发布或 PyPI 条目。
预发布	vX.Y.Z-rc.N，在其发布拉取请求中计算并审核	PyPI（以预发布版本 X.Y.ZrcN 发布）；GitHub 发布，附带 wheel、sdist、.deb/.rpm 软件包、.mcpb 捆绑包、插件 .zip 和 SBOM；Docker 镜像使用不可变的 vX.Y.Z-rc.N 标签，以及可感知排序的滚动 rc 标签。不发布到插件市场和 MCP 注册表，也不部署文档。
稳定版	vX.Y.Z	所有内容：PyPI、Docker（版本标签以及可感知排序的 latest / vX / vX.Y）、.deb/.rpm、GitHub 发布资产（wheel、sdist、.mcpb 捆绑包、插件 .zip、SBOM）、插件市场和 MCP 注册表条目（若该版本是最新稳定版），以及带有可感知排序的 latest 别名的版本化文档。

预发布版本会发布到 PyPI，以便候选版本的 .mcpb 捆绑包能够安装：该捆绑包指向 PyPI，而不是随附代码。普通安装程序不会看到它们，因为 PEP 440 解析器会跳过预发布版本，除非依赖项明确指定该版本，或传入 --pre。使用 pip install pvliesdonk-scholar-mcp==X.Y.ZrcN 按名称请求候选版本。PyPI 使用 PEP 440 规范形式，而标签使用 SemVer。滚动指针会感知版本顺序，因此从旧的 release/X.Y 分支切出的补丁版本不会将 latest 一类标签回退到较旧内容，而已发布版本的候选版本也不会让 rc 回退。完整模型请参阅发布流程。

快速入门

scholar-mcp serve                                # stdio transport
scholar-mcp serve --transport http --port 8000   # streamable HTTP

如需在库中使用（嵌入领域逻辑而不使用 MCP 传输），请直接从 scholar_mcp 包导入。入口点请参阅项目在 src/scholar_mcp/ 下的领域模块。

服务信息

服务通过 fastmcp_pvl_core.register_server_info_tool 注册内置的 get_server_info 工具，方便运营人员通过一次 MCP 调用确认已部署的版本。默认响应包含 server_name、server_version 和 core_version。与远程上游通信的服务，会在 src/scholar_mcp/server.py 的 DOMAIN-UPSTREAM-START / DOMAIN-UPSTREAM-END 哨兵标记内接入上游版本报告；接线模式请参阅 tool-registration。

健康状态

服务通过 fastmcp_pvl_core.register_health_routes 在 MCP 挂载点和身份验证之外提供 /health（存活状态，静态返回 200）和 /health/ready（就绪状态，后端存储或领域检查失败时返回 503）。compose.yml 会探测前者。领域就绪检查应放在 src/scholar_mcp/server.py 的 health_checks 字典中；有关路由、挂载路径规则和 SCHOLAR_MCP_HEALTH_DETAIL，请参阅 Docker 部署。

配置

最常见的环境变量，适用于所有基于 fastmcp-pvl-core 的服务：

变量	默认值	描述
SCHOLAR_MCP_KV_STORE_URL	file:///data/state	供所有需要状态的 pvl-core 子系统共享的持久状态后端 URL。memory:// 在进程内使用，重启后数据会丢失；file:///path 会在一台服务器上持久保存；redis://、dynamodb:// 和 mongodb:// 均需要对应的 extra。未设置时，默认使用 file:///data/state（Docker 镜像挂载的卷目录）；如果主机上该目录不可用，则使用 memory://（并显示警告）。
SCHOLAR_MCP_LOG_LEVEL	INFO	进程中所有记录器（包括 FastMCP）的日志级别（DEBUG / INFO / WARNING / ERROR / CRITICAL）。-v CLI 标志会覆盖此设置并改为 DEBUG。不带前缀的 FASTMCP_LOG_LEVEL 在一个主要版本周期内仍然有效，但会记录弃用警告。
SCHOLAR_MCP_LOG_FORMAT	（无）	日志呈现格式。rich 会为终端上的每条记录输出一行彩色的 event key=value；json 会为日志收集器输出一条 JSON 对象。未设置时，如果 stderr 是终端，则使用 rich；其他情况下使用 json，因此容器或 journald 无需配置即可获得 JSON。

此表和域配置下的表都是精选子集。完整的生成版参考文档列出了服务器读取的所有变量，详见配置参考；.env.example 以便于复制粘贴的形式列出了相同的配置项。

身份验证

调用方通过承载令牌或 OIDC 进行身份验证（二者不可同时使用）。有关设置、映射多主体令牌、OIDC 和故障排除，请参阅身份验证指南。

脚手架生成后的检查清单

执行 copier copy 和 gh repo create --push 后：

1. 填写 README 和 AGENTS.md 中的 DOMAIN 块（每个带有 DOMAIN 哨兵注释的部分）。GENERATED-ENV-TABLE-* 区域不是 DOMAIN 块；配置生成器负责管理这些区域，并会在每次运行时重写它们。
2. 配置 GitHub 密钥（见下文）。
3. 安装开发和文档工具：uv sync --all-extras --all-groups。
4. 安装 pre-commit 钩子：uv run pre-commit install。
5. 在本地运行检查：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
6. 推送第一个提交。CI 应当通过。

GitHub 密钥

CI 工作流引用了两个必需的仓库密钥和一个可选的 Claude 令牌。请通过 Settings → Secrets and variables → Actions 或使用 gh secret set 进行配置：

密钥	用途	生成方式
RELEASE_TOKEN	release-prepare.yml、release.yml、copier-update.yml、renovate.yml、bootstrap.yml	在 https://github.com/settings/personal-access-tokens/new 创建细粒度 PAT，并授予 contents: write、pull_requests: write 和 administration: write 权限（bootstrap 会应用仓库规则集、自动合并、安全设置和 About 区块）。令牌必须属于仓库管理员：已提供的规则集授予管理员角色绕过权限，而 knope 在发布拉取请求合并后创建的发布标签和 GitHub Release 也依赖此权限（令牌创建的拉取请求也需要此权限才能运行 CI）。范围仅限此仓库。
SONAR_TOKEN	ci.yml	https://sonarcloud.io：导入仓库后，打开其 Administration → Analysis Method 页面。先在此关闭 Automatic Analysis，因为开启时 SonarQube Cloud 会拒绝 CI 扫描；选择 GitHub Actions 后即可看到令牌。在创建此密钥之前，CI 会跳过扫描。
CLAUDE_CODE_OAUTH_TOKEN	claude.yml	可选。在本地运行 claude setup-token，仅在使用 @claude 或选择启用自动审查时配置此项。

gh secret set RELEASE_TOKEN
gh secret set SONAR_TOKEN
# Optional: enables @claude and opted-in automatic review.
gh secret set CLAUDE_CODE_OAUTH_TOKEN

依赖更新由 Renovate（renovate.yml）处理，并复用 RELEASE_TOKEN。它会维护 uv.lock，并在 CI Success 检查通过后自动合并补丁和次要版本更新；bootstrap.yml 会启用自动合并、应用仓库规则集（.github/rulesets/）、开启私有漏洞报告和 Dependabot 警报，并在首次推送时根据 pyproject.toml 填写仓库的 About 区块（描述、网站、主题）。有关各分支的保护措施、绕过机制和安全设置，请参阅 Repository Protection。GitHub Actions 会在 copier 模板中更新，并通过 copier update 引入，而不是逐个仓库更新。

GITHUB_TOKEN 会自动提供；无需操作。

本地开发

PR 门禁（与 CI 一致）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

Pre-commit 会在每次提交时运行门禁中的部分检查；详情请参阅 .pre-commit-config.yaml，或查看 AGENTS.md 了解完整的 Hard PR Acceptance Gates。

CI 要求在 Python 3.11 到 3.14 上通过测试。Python 3.14 还会收集 分支覆盖率，并强制要求总体覆盖率和补丁覆盖率达到 80%。 如需复现该测试命令，请运行 uv run --python 3.14 pytest --cov --cov-report=xml --durations=20。

故障排除

移动已生成脚手架的项目

uv sync 会创建 .venv/bin/* 脚本，其中包含指向虚拟环境 Python 的绝对 shebang。如果在生成脚手架后移动仓库（mv /old/path /new/path），uv run pytest 会因 ModuleNotFoundError: No module named 'fastmcp' 而失败，因为过期的 shebang 会解析到与虚拟环境 site-packages 不同的解释器。

修复方法：

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest 也可作为一次性解决方法（绕过过期的入口脚本 shim）。

copier update 后刷新 uv.lock

当 copier update 引入新依赖时（例如 pyproject.toml.jinja 中新增 extra），CI 安装步骤运行 uv sync --locked 会因锁文件过期而失败。请在本地运行 uv lock，并在接受 copier-update PR 时一并提交刷新后的 uv.lock。

CI 使用 --locked 安装（审查工作流则使用 --frozen），因此任何作业都不会在自己的工作区中重写 uv.lock：重新锁定的作业会掩盖刚修复的偏差，而工作区变更也会导致同一作业中后续的 git checkout 失败。锁文件偏差会显示为明确报错的安装步骤，而不是静默修改。

贡献

CONTRIBUTING.md 载有问题和拉取请求的规则，并说明修复应归属何处：库代码归 fastmcp-pvl-core，模板自有文件归模板，本仓库中属于 DOMAIN-* / CONFIG-* / PROJECT-* 区块的内容则归本仓库。AGENTS.md 载有约定和门禁要求；.agents/skills/ 下的技能载有任务流程，其中包括 self-reviewing（提交拉取请求前在本地进行自我审查）、writing-release-notes（编写发布说明）、applying-template-updates（每周模板更新拉取请求）和 authoring-issues-prs（提交问题和拉取请求）。发布流程见 docs/deployment/release-process.md；模板更新流程见 docs/deployment/template-updates.md。SECURITY.md 说明如何私下报告漏洞，以及报告后应有哪些预期。

链接

• 文档
• llms.txt
• FastMCP
• fastmcp-pvl-core

领域配置

本项目将以下变量作为入口点（领域变量使用 SCHOLAR_MCP_ 前缀）：

变量	默认值	必需	说明
SCHOLAR_MCP_READ_ONLY	true	否	为 true 时，带有写入标签的工具（PDF 下载和转换缓存写入）将被隐藏。设为 false 可启用这些工具。
SCHOLAR_MCP_S2_API_KEY	(none)	否	Semantic Scholar API 密钥。此项可选，但强烈建议配置：密钥可获得初始的 1 req/s 配额；匿名用户共享容量，可能会受到限流。请在 https://www.semanticscholar.org/product/api#api-key-form 申请。
SCHOLAR_MCP_DOCLING_URL	(none)	否	正在运行的 docling-serve 实例的基础 URL，用于转换 PDF（例如 http://localhost:5001）。未设置时，PDF 转换工具会返回错误。
SCHOLAR_MCP_CACHE_DIR	/data/scholar-mcp	否	SQLite 缓存数据库（cache.db）和已下载 PDF（pdfs/, md/）的目录。
SCHOLAR_MCP_CONTACT_EMAIL	(none)	否	用于 OpenAlex 礼貌池的联系邮箱（可提高速率限制）。同时启用 Unpaywall 查询，作为 PDF 的备用来源。

此处仅列出精选子集：当字段的 tags 元数据包含 readme 时，才会在此处显示。所有领域变量都记录在配置参考中，并按配置向导呈现的相同方式分组。

领域配置字段在 src/scholar_mcp/config.py 中的 CONFIG-FIELDS-START / CONFIG-FIELDS-END 标记之间组合；环境变量读取通过 fastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default) 完成，以确保命名一致；字段不变量则写在 CONFIG-VALIDATE-START / CONFIG-VALIDATE-END 标记之间的 __post_init__ 中。每个字段的 metadata 中的 help、tags 和 wizard 分组会直接生成参考表，因此请确保这些内容准确且完整。

关键设计决策

• 库优先，MCP 可选。 核心领域逻辑（S2/EPO/Open Library/标准客户端、丰富化流水线、缓存）无需 FastMCP 即可导入；MCP 服务只是一个轻量的异步封装。这样便于在脚本、笔记本和其他服务中复用。
• 同步领域代码，异步 MCP 层。 后端客户端采用同步方式；MCP 工具通过 asyncio.to_thread() 调用它们。客户端代码更简单，并在传输边界明确地将任务移出主线程。
• 按表设置 TTL 并支持标识符别名的 SQLite 缓存。 论文/作者缓存 30 天，引文/参考文献缓存 7 天。即使清除缓存，DOI ↔ S2 ID ↔ arXiv ID 的别名关系也会保留，因此重复的丰富化操作会命中同一行。
• 默认只读。 带有写入标记的工具（PDF 下载/转换、专利 PDF）仅在 SCHOLAR_MCP_READ_ONLY=false 时显示。首次运行时采用更安全的默认设置。
• 耗时操作会转为后台任务。 所有可能长时间运行的工具都使用 fastmcp-pvl-core 任务层。若调用在 SCHOLAR_MCP_JOBS_SOFT_DEADLINE_S 规定的时限内完成，则直接返回结果；否则返回一个句柄，可通过 get_job_result 轮询。S2 支持的工具在 Semantic Scholar 限流时，也会立即返回一个说明原因的句柄。任务会从暂停处继续运行，命中缓存时仍会直接返回结果。
• 等待 EPO 限流解除，而不是排队。 每次请求前都会查询流量指示器，并缓存一分钟，因此在此之前重试只会重新读取缓存，不会再次查询。每次退避等待时间都长于缓存时间；如果当天配额已用尽，则会立即报告，因为当天不会恢复。
• 第 2 级标准数据同步在带外进行。 ISO/IEC/IEEE/CC/CEN 目录来自社区 Relaton 数据转储，通过 scholar-mcp sync-standards 同步，而不是在运行时实时获取。这既避免了抓取受付费墙限制的 HTML，也能让工具调用保持快速。