Scholar MCP

寻找论文。追踪证据。构建领域。

Scholar MCP 可根据自然语言问题查找论文、追踪引用和相关研究，并打开原文。您可以将选定的论文和笔记保存在本地文献库中，让研究成果在不同会话间延续。

快速演示

一次连贯的 Agent 工作流：search_papers → build_paper_graph → paper_info + read_paper → paper_library → 文献库连接器。

工作原理

Agent 通过 stdio 或 Streamable HTTP 调用类型化 MCP 工具。Scholar 返回简洁文本和结构化数据，同时由持久化的 SQLite 文献库支持 FTS5 搜索、PDF 附件、JSONL 快照，以及 Obsidian、Zotero 和 Notion 连接器。

快速开始

Claude Code：

claude mcp add scholar -- uvx --python 3.12 \
  --find-links https://github.com/Liyux3/scholar-mcp/releases/download/v0.8.5/wheel-index.html \
  --from 'scholar-mcp[rerank]==0.8.5' scholar-mcp

Claude Desktop 或任何 stdio MCP 客户端：

{
  "mcpServers": {
    "scholar": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--find-links", "https://github.com/Liyux3/scholar-mcp/releases/download/v0.8.5/wheel-index.html",
        "--from", "scholar-mcp[rerank]==0.8.5", "scholar-mcp"
      ]
    }
  }
}

直接运行的服务提供精简核心配置。请安装 uv；它会自动准备 Python 3.12 和 CPU 重排器。可选的源密钥可解锁更广的覆盖范围和更高的吞吐量。macOS 桌面应用包内含 Python 和依赖项；便携式启动器也能在未安装 uv 的机器上运行。

仓库还附带一个研究插件，包含引文图谱、本地论文库和 Deep Research 技能：

# Codex
codex plugin marketplace add Liyux3/scholar-mcp
codex plugin add scholar-mcp@scholar-mcp

# Claude Code
claude plugin marketplace add Liyux3/scholar-mcp
claude plugin install scholar-mcp@scholar-mcp

同一插件目录遵循 Agent Plugins 标准，可用于 Cursor、Pi 及兼容的运行环境。OpenCode 可以将 uvx scholar-mcp 作为本地 MCP 启动；Pi 可以使用 pi-mcp-adapter。

发布制品还包括 PyPI 包、多架构 GHCR 镜像和 macOS MCPB 包。请参阅完整的分发矩阵。

工具

scholar://status 会报告数据源的可用性和实际使用的重排器，不会占用工具界面。工具响应保留简洁的 YAML 文本，同时也提供结构化 MCP 数据。

捆绑的 Deep Research 技能可将搜索、论文检查、图谱遍历和选定的文库写入操作整合为一份动态领域图谱。

检索

关键词 API 会收到经过测算的、针对特定数据源的查询预算。语义端点会保留原始问题。每个数据源都会独立为同一个规范化证据池提供内容。 结果会根据 DOI、arXiv、Semantic Scholar、OpenAlex、PubMed 和 OpenReview 标识进行规范化。重复记录会补充互补元数据和独立来源证据，而不是重复显示多次。

配置后，DashScope qwen3-rerank 会作为主要重排器。安装 rerank extra，以启用 FlashRank 本地回退：uvx --from 'scholar-mcp[rerank]' scholar-mcp。容器和 MCPB 包含此 extra；本地模型会在首次使用时下载，并保存在应用数据目录中。搜索会先对初始匹配结果排序，再从最相关的论文中追踪关联，最后对合并后的结果重新排序。元数据补全与来源检索并行进行；对于大型候选池，会分批评分，并遵守模型服务的文档数和令牌限制。

DASHSCOPE_HTTP_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/api/v1
SCHOLAR_RERANK_MODEL=qwen3-rerank

Request:  query, documents, top_n, model
Response: results: [{index, relevance_score}]

常规响应以论文为主，并会在可用性影响搜索时附上简短警告。debug=true 会添加 _meta，其中包含来源覆盖情况、实际使用的重排器、各来源的结果数、延迟、来源信息和详细错误。并行搜索的基础时限为 30 秒，可通过 SCHOLAR_SOURCE_BUDGET_S 配置。Google Scholar 分页最多可将时限延长至 120 秒，以保留已完成的多页结果。

检索质量测量

在冻结的匹配 LitSearch 测试中，与 Exa research-paper search 相比，Scholar 的 前五项查询命中率高出 10 个百分点，前二十项高出 6 个百分点。

Scholar 找到了 Exa 未命中的 9 个前五项结果；Exa 找到了 Scholar 未命中的 4 个。

引用图谱与论文库

此图由本地实时收藏集生成，可展示研究领域的基础论文、桥接论文，以及推动领域发展的论文。稳定的标识符和并行引用遍历能在图谱不断扩展时保持其连通性。

论文库使用一个持久化 SQLite 权威数据源，通过 WAL 事务和 FTS5 搜索。现有 JSONL 收藏集会自动迁移，并继续作为兼容性快照提供。稳定标识符、笔记、标签、PDF 路径、连接器 ID 和同步修订版本都会关联到同一条规范记录。

默认数据布局：

~/.scholar-mcp/
├── papers/    persistent PDFs
├── kb/
│   ├── library.sqlite3    authority + FTS5 + sync state
│   └── *.jsonl            compatibility snapshots
└── vault/                 Markdown projections and wikilinks

文献库连接器

# No login: write directly into an Obsidian vault
scholar-mcp library export obsidian --collection rag --path /path/to/vault

# Dry-run by default; add --apply for external writes
scholar-mcp library sync zotero --collection rag
scholar-mcp library publish notion --collection rag

Obsidian 是实时 Markdown 投影。Zotero 管理书目条目、文集、标签和笔记。Notion 接收单向的待读列表视图。外部连接器会在 SQLite 中保存其 ID、版本和内容哈希，因此不会重复发布未更改的论文。

论文访问

read_paper 使用临时 PDF，默认读取第 1 至 10 页，通常足以读到 AI 会议论文的结论。它会返回带页码的 Markdown、在表格几何信息可靠时返回结构化表格，并为图表和视觉表格回退方案提供说明文字选择器。传入 visual="Figure 3" 或其他返回的选择器，即可连同文本一起获取一张聚焦的页面裁剪图。传入 pages="11-20" 可继续读取参考文献或附录。提取完成后会删除 PDF。download_paper 会将内容流式写入暂存文件，以原子方式发布经过验证的 PDF，复用有效的本地副本，并将其元数据编入所选文集。

通用解析链涵盖：

1. 原生开放获取记录和 arXiv、Europe PMC 等规范档案
2. 已注册的存储库解析器：CORE、OpenAIRE、HAL、Zenodo 和 DOAJ
3. bioRxiv、medRxiv、SSRN、ChemRxiv 等预印本服务
4. Unpaywall 和可选的机构代理

scholar-mcp sources 会打印根据注册表生成的能力矩阵。添加 --check 可测试已配置的搜索提供方；添加 --check --source arxiv --query "retrieval augmented generation" 可检查单个提供方。arXiv 的 Atom API 不可用时，会回退到其自身的 HTTPS 搜索。Zenodo 参与 PDF 解析，但不会纳入默认发现，因为其范围广泛的出版记录带来的候选噪声多于检索价值。

图书馆代理访问

对于付费墙论文，download_paper 可以通过大学图书馆的 EZproxy 登录获取论文。它会在 Unpaywall 之后、可选的 Sci-Hub 步骤之前运行，且只用于你请求的单篇论文。Scholar 不会索要或存储密码，而是复用你登录后从自己的浏览器导出的会话 Cookie。

1. 将 LIBRARY_PROXY_PREFIX 设置为图书馆代理登录前缀，即论文地址之前的部分，例如 https://proxy.library.example.edu/login?url=。可从任何代理链接或图书馆的书签脚本中复制；这里不假设任何特定机构。
2. 在 Edge 或 Chrome 中登录图书馆代理，并打开任意代理页面。
3. 使用支持 cookies.txt 扩展程序的方式，以 Netscape cookies.txt 格式导出代理域名的 Cookie（例如 Get cookies.txt LOCALLY；Edge 可以安装 Chrome 网上应用店中的扩展程序）。将文件保存在私密位置，并将 LIBRARY_PROXY_COOKIES 设置为该文件的路径。
4. 重启 MCP 客户端，使其读取新的环境变量。

图书馆会话的有效期较短，由图书馆控制，因此导出的文件会在数小时后或图书馆结束会话时失效。当代理返回登录页面时，下载消息会提示会话已过期；请重新登录并导出新文件。该文件是有效的会话凭据，请勿将其放入 Git 或共享文件夹。系统只会读取属于代理域名的 Cookie；文件中的其他 Cookie 都会被忽略。下载失败时，消息会附带一个代理链接，你可以在已登录的浏览器中打开该链接。

如果终端使用 HTTP 代理，请确保图书馆请求与已登录的浏览器使用相同的网络路由。如需直接访问图书馆，请将其代理主机名和子域名添加到 NO_PROXY。

配置

所有凭据均为可选项，并保留在 MCP 进程环境中。

返回给模型的错误会隐藏请求 URL 和凭据。 OpenReview 公开投稿可在无需账号或密码的情况下搜索。

开发

git clone https://github.com/Liyux3/scholar-mcp.git
cd scholar-mcp
uv sync --extra dev
uv run pytest

默认运行单元测试。使用 uv run pytest -m integration 单独运行实时 API 测试。

连接器和功能贡献请遵循 CONTRIBUTING.md。请通过 SECURITY.md 中的私密流程报告安全问题；引文元数据见 CITATION.cff。

本地和 Docker 客户端默认使用 stdio。设置 SCHOLAR_MCP_TRANSPORT=http 可启用 Streamable HTTP；默认端点为 /mcp。

许可证

Apache License 2.0