scholar

学术 MCP 服务

一个 Model Context Protocol（MCP）服务，可结构化访问科学文献数据库。它为 Scopus、OpenAlex、Semantic Scholar 和 Unpaywall 提供统一接口，使 AI Agent 能够系统地发现论文、消歧作者、追踪引文脉络并提取多模态内容。

核心功能

• 统一文献搜索

  • Semantic Scholar 集成 — 高相关性搜索和详细元数据，包括 AI 生成的 TLDR（需要 API 密钥）。
  • Scopus 集成 — 通过高级布尔语法定向检索元数据（需要 API 密钥）。
  • OpenAlex 集成 — 跨 2.5 亿余篇作品进行广泛搜索，并重构摘要。
  • Unpaywall 解析 — 在全球开放获取资源库中交叉检索 DOI 并定位 PDF。
  • Sci-Hub 后备方案（⚠️ 谨慎使用） — 自动解析镜像并抓取内容，以绕过付费墙。

• 图书搜索与提取

  • Google Books 和 Open Library — 集成搜索图书元数据、版本和简介，无需 API 密钥。
  • Library Genesis（Libgen） — 使用 PyMuPDF 直接搜索图书并提取全文。提供智能缓存和节省令牌的策略（目录读取、定向关键词搜索和页面范围提取）。

• 作者识别与指标

  • 通过 OpenAlex 自动补全，即时消歧作者并解析 ID。
  • 综合档案：H 指数、i10 指数、机构隶属关系历史记录和 ORCID 关联。
  • 通过 Elsevier（Scopus）获取精确指标，核实发表数量。

• 引文脉络追踪

  • 通过前向引文（引用作品）和后向参考文献（被引作品）绘制研究演进脉络。

• 结构化与多模态提取

  • 文本提取 — 使用 PyMuPDF 对开放获取 PDF 进行感知布局的解析。
  • 视觉渲染 — 逐页渲染为 PNG，以便通过大模型分析图表、表格和公式。
  • HTML 后备方案 — 通过 BeautifulSoup 从基于网页的研究资源中提取内容。

• 主题映射与领域分析

  • 发现概念和领域层级，以绘制研究领域图谱。
  • 批量检索元数据，支持高吞吐量文献处理（每次请求最多 50 个 DOI）。

• 访问管理与后备方案

  • 自动检测非开放获取内容，并提供人工介入说明以便手动上传。

架构

graph TD
    A[LLM Agent] -->|MCP Protocol| B(Scholar MCP Server)
    B --> C{Database Router}
    C -->|Primary| D[Scopus API]
    C -->|Fallback| E[OpenAlex API]
    C -->|DOI Resolver| F[Unpaywall API]
    C -->|Citations| P[CrossRef API]
    
    D --> G{Access Check}
    E --> G
    F --> G
    P --> G
    
    G -->|Open Access| H[PDF Buffer Download]
    G -->|Closed Access| I[Human-in-the-Loop Prompt]
    H --> J[PyMuPDF Text Extractor]
    H --> K[PyMuPDF Vision Renderer]
    J --> L[Return Context to LLM]
    K --> L
    I --> L
    B --> M{Author Router}
    M -->|Profile| N[OpenAlex Authors API]
    M -->|Metrics| O[Scopus Author API]
    N --> L
    O --> L

安装

快速开始（通过 PyPI）

通过 PyPI 直接使用此服务是最快的方法：

pip install scholar-academic-mcp

手动设置（用于开发）

# Clone the repository
git clone https://github.com/mlintangmz2765/Scholar-MCP.git
cd Scholar-MCP

# Setup virtual environment
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate # Unix

# Install in editable mode
pip install -e .

环境变量

变量	必需	说明
SCOPUS_API_KEY	是	用于 Scopus 搜索和作者检索的 Elsevier API 密钥。
S2_API_KEY	否	用于 TLDR 和 S2 图谱访问的 Semantic Scholar API 密钥。
SCIHUB_MIRRORS	否	用逗号分隔的可用 Sci-Hub 镜像列表，用作 PDF 后备来源。
LIBGEN_MIRRORS	否	用逗号分隔的可用 Library Genesis 镜像列表。
SCOPUS_INST_TOKEN	否	通过 Scopus 获取完整摘要的机构令牌。
CONTACT_EMAIL	是	用于 OpenAlex/Unpaywall 礼貌池 API 路由的电子邮件地址。

配置

Claude Desktop / Cursor

将以下内容添加到配置文件中（例如，claude_desktop_config.json）：

{
  "mcpServers": {
    "scholar-academic-mcp": {
      "command": "scholar-academic-mcp",
      "env": {
        "SCOPUS_API_KEY": "your_scopus_api_key",
        "S2_API_KEY": "your_s2_api_key",
        "SCIHUB_MIRRORS": "https://sci-hub.ru,https://sci-hub.st",
        "LIBGEN_MIRRORS": "https://libgen.la,http://libgen.li",
        "SCOPUS_INST_TOKEN": "your_optional_inst_token",
        "CONTACT_EMAIL": "[email protected]"
      }
    }
  }
}

快速入门与示例

配置完成后，你的 AI Agent 即可执行复杂的研究工作流。以下是具有代表性的工具输入和结构化输出示例。

1. 文献发现（Scopus）

提示词：“使用 Scopus 查找 2022 年后发表的关于 ‘Transformer architectures’ 的近期论文。”

工具调用：search_papers_tool(query="TITLE-ABS-KEY(Transformer architectures) AND PUBYEAR > 2022", limit=3)

输出：

Found 3 papers via Scopus:
- [SCOPUS_ID:85184...] Attention is All You Need? A Survey of Transformer Variants
  Authors: Smith, J., Doe, A.
  Date: 2024-01-15 | DOI: 10.1016/j.artint.2023.104012

2. 多模态内容分析

提示词：“我想查看此 URL 中第 3 页的神经网络架构图。”

工具调用：get_full_text_visual_tool(url="https://arxiv.org/pdf/1706.03762.pdf", max_pages=3)

输出：

• [Text]“已成功以可视化方式渲染 3 页……”
• [Image]（第 1 页的 PNG 数据）
• [Image]（第 2 页的 PNG 数据）
• [Image]（第 3 页的 PNG 数据，包含架构图）

3. 研究主题映射

提示词：“帮我了解与 ‘Generative AI’ 相关的子领域和领域。”

工具调用：search_topics_tool(query="Generative AI")

输出：

Found 1 topics for 'Generative AI':
- Artificial Intelligence
  Hierarchy: Computer Science → Artificial Intelligence → Machine Learning
  Works: 12,450 | Citations: 450,210
  Description: A field of computer science that focuses on creating systems capable of generating...

工具

该服务在 7 个类别中注册了 23 个工具：

论文发现

工具	签名	描述
search_papers_tool	(query, limit=5, use_scopus=True, sort_by="relevance")	通过 Scopus（布尔语法）或 OpenAlex 搜索论文。可按 cited_by_count 或 publication_year 排序。
search_papers_s2_tool	(query, limit=5)	通过 Semantic Scholar 搜索论文。注意：严格限制为每秒 1 次请求。
get_paper_details_tool	(paper_id)	根据 Scopus ID、DOI 或 OpenAlex ID 获取完整元数据和摘要（自动路由）。
get_paper_details_s2_tool	(paper_id)	从 Semantic Scholar 获取完整元数据，包括 AI 生成的 TLDR。接受 S2 ID 或 DOI。
search_titles_unpaywall_tool	(query, is_oa=None)	直接按标题搜索 Unpaywall 的数据库。设置 is_oa=True 可仅返回开放获取结果。
get_related_works_tool	(paper_id, limit=10)	使用 OpenAlex 的文献耦合功能查找相关或相似论文。

图书发现与提取

工具	签名	描述
search_books_tool	(query, limit=5, source="googlebooks")	通过 Google Books 或 Open Library 搜索图书元数据。
get_book_details_tool	(book_id, source="googlebooks")	获取完整的图书详情、简介和 ISBN。
search_libgen_tool	(query, limit=5)	在 Library Genesis 中搜索图书，以获取其下载 MD5 哈希值。
interact_with_book_tool	(md5, action, keyword, start_page, end_page)	从 Libgen 智能提取内容。操作：toc（目录）、search（关键词）、pages（页码范围）。

作者分析

工具	签名	描述
autocomplete_authors_tool	(name, limit=5)	快速消除作者姓名歧义，并解析 OpenAlex 作者 ID。
search_authors_tool	(name, institution=None, limit=5)	详细的文献计量档案：H 指数、i10 指数、ORCID 和研究概念。
search_author_by_orcid_tool	(orcid)	通过 ORCID（原始格式或 URL 格式）直接查找作者。
retrieve_author_works_tool	(author_id, limit=15)	获取指定 OpenAlex 作者按时间顺序排序的出版物。
get_author_profile_scopus_tool	(author_id)	获取来自 Scopus 的精确 h 指数、引用次数和所属机构信息。
get_author_profile_s2_tool	(author_id)	获取 Semantic Scholar 作者档案（H 指数、论文数量、引用次数）。

引文追踪

工具	签名	描述
get_citations_tool	(paper_id, direction="references")	通过 OpenAlex 获取前向引用或后向参考文献。

全文与 PDF

工具	签名	描述
get_full_text_tool	(url, start_page=None, end_page=None)	从 OA PDF 或 HTML 页面提取文本。支持选择页码范围。
get_full_text_visual_tool	(url, max_pages=3)	将 PDF 页面渲染为图像，供支持视觉能力的大模型使用。
fetch_pdf_text_unpaywall_tool	(doi)	一站式操作：通过 Unpaywall 解析 DOI → 下载 PDF → 提取文本。
get_scihub_link_tool	(doi)	尝试使用 Sci-Hub 将严格付费墙保护的 DOI 解析为免费的 PDF 直链。
fetch_pdf_text_scihub_tool	(doi)	一站式绕过付费墙：通过 Sci-Hub 解析 DOI → 下载 PDF → 提取文本。

引用与写作

工具	签名	描述
get_bibtex_tool	(doi)	通过 CrossRef 内容协商生成 LaTeX 的 BibTeX 条目。
format_citation_tool	(doi, style="apa")	按 APA、IEEE、Chicago、Harvard、Vancouver、MLA 或 Turabian 格式化引用。

开放获取解析

工具	签名	描述
get_unpaywall_link_tool	(doi)	通过 Unpaywall 将 DOI 解析为所有可用的 OA 来源。

主题映射与批量分析

工具	签名	描述
search_topics_tool	(query, limit=10)	浏览研究主题／概念。返回领域、学科和出版物数量。
batch_lookup_tool	(dois: list[str])	在一次调用中批量获取多个 DOI 的元数据（最多 50 个）。

技术设计与可靠性

Scholar MCP 专为高风险研究环境中的精确性和容错能力而设计，通过多层保护确保数据完整性：

• 严格的数据契约（Pydantic）

  • 所有上游 API 响应在返回给 Agent 之前，都会通过 Pydantic 模型进行验证。
  • 即使上游数据库架构发生变化，也能确保接口可预测且类型安全。

• 容错网络（Tenacity）

  • 使用 tenacity 集成了指数退避，用于处理临时 HTTP 错误（429、5xx）。
  • 支持可配置的速率限制感知，以便通过 Elsevier 和 OpenAlex 的“polite pool”路由请求。

• 资源安全与并发

  • 上下文管理的提取器：自动清理 PDF 缓冲区和文件描述符。
  • 隔离并发：批量操作使用 asyncio.gather，并进行局部异常处理，以防止整个会话失败。

• 系统可观测性

  • 结构化标准错误（stderr）日志可在工具生命周期内提供执行情况，同时不干扰 MCP JSON-RPC 协议。

• 自动化验证

  • 完整的测试套件使用 respx 进行确定性 API 模拟，无需外部网络即可确保覆盖所有边界情况。

项目结构

Scholar-MCP/
├── .github/workflows/ # GitHub Actions (CI & Releases)
├── scripts/           # Automation & Validation scripts
├── tests/             # Pytest suite (respx mocked)
├── server.py          # FastMCP tool entry point
├── api.py             # API Clients (Scopus, OpenAlex, Unpaywall, CrossRef)
├── extractor.py       # PDF/HTML Extraction & Rendering
├── models.py          # Pydantic Data Validation
├── server.json        # MCP Registry Manifest
├── pyproject.toml     # Python packaging configuration
├── requirements.txt   # Dependencies
├── VERSION            # Version tracking (v1.0.0)
├── LICENSE            # MIT License
├── README.md          # Documentation
├── .env.example       # Template for API keys
└── .gitignore         # Git exclusion rules

故障排查

症状	原因	解决方法
Scopus 返回 HTTP 401	标准 API 密钥没有 META_ABS 视图访问权限。	设置 SCOPUS_INST_TOKEN，或使用 OpenAlex 作为备用方案。
下载 PDF 时出现 HTTP 403	出版商的反机器人保护（Cloudflare、DataDome）。	手动将 PDF 提供给大模型。
Unpaywall 结果为空	论文受到严格付费墙限制，没有开放获取副本。	通过 ResearchGate 或机构访问权限向作者索取 PDF。
未设置 SCOPUS_API_KEY is not set	缺少环境变量。	确保已配置 .env，或通过 MCP 客户端的 env 块传递。

贡献

1. Fork 此仓库。
2. 创建功能分支（git checkout -b feature/my-feature）。
3. 提交更改（git commit -m 'feat: add new capability'）。
4. 将分支推送到远程仓库（git push origin feature/my-feature）。
5. 发起 Pull Request。

请确保所有代码均遵循 PEP 8 规范。

许可证

MIT 许可证。详情请参阅 LICENSE。

---

免责声明： 自动查询出版商 API 时，必须遵守 Elsevier、OpenAlex 和 Unpaywall 各自的服务条款。请勿分发 API 密钥。请遵守所有适用的速率限制。

mcp-name: io.github.mlintangmz2765/scholar