Semantic Scholar MCP Server

Semantic Scholar MCP 服务

基于 FastMCP 实现的 Semantic Scholar API 服务，可全面访问学术论文数据、作者信息和引用网络。

在寻找 Claude Code 技能？ 请查看 semantic-scholar-skills——新一代工具包，集成了此 MCP 服务、开箱即用的 Claude Code 技能（/expand-references、/trace-citations、/paper-triage）以及 Python 工作流引擎。

项目结构

项目已重构为模块化结构，以便于维护：

semantic-scholar-server/
├── semantic_scholar/            # Main package
│   ├── __init__.py             # Package initialization
│   ├── server.py               # Server setup and main functionality
│   ├── mcp.py                  # Centralized FastMCP instance definition
│   ├── config.py               # Configuration classes
│   ├── utils/                  # Utility modules
│   │   ├── __init__.py
│   │   ├── errors.py           # Error handling
│   │   └── http.py             # HTTP client and rate limiting
│   ├── api/                    # API endpoints
│       ├── __init__.py
│       ├── papers.py           # Paper-related endpoints
│       ├── authors.py          # Author-related endpoints
│       └── recommendations.py  # Recommendation endpoints
├── run.py                      # Entry point script

此结构：

• 将不同职责拆分到逻辑模块中
• 让代码库更易于理解和维护
• 便于测试和未来扩展
• 将相关功能归类在一起
• 集中管理 FastMCP 实例，避免循环导入

功能

• 论文搜索与发现

  • 支持高级筛选的全文搜索
  • 基于标题匹配论文
  • 论文推荐（单篇和多篇）
  • 批量获取论文详情
  • 支持排序策略的高级搜索

• 引用分析

  • 探索引用网络
  • 跟踪参考文献
  • 分析引用上下文和影响力

• 作者信息

  • 搜索作者并查看个人资料详情
  • 出版记录
  • 批量获取作者详情

• 高级功能

  • 支持多种排序策略的复杂搜索
  • 可自定义字段选择
  • 高效的批量操作
  • 遵循速率限制
  • 支持已认证和未认证访问
  • 平稳关闭和错误处理
  • 连接池和资源管理

系统要求

• Python 3.10+
• API 密钥环境变量（可选）

安装

快速安装（PyPI）

pip install semantic-scholar-fastmcp

也可以使用 uvx 直接运行：

uvx semantic-scholar-fastmcp

MCP 客户端配置

适用于任何支持 uvx 的 MCP 客户端：

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["semantic-scholar-fastmcp"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
      }
    }
  }
}

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Semantic Scholar MCP 服务：

npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude

手动安装

1. 克隆代码库：

git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git
cd semantic-scholar-fastmcp-mcp-server

2. 以开发模式安装：

pip install -e ".[dev]"

3. 运行服务：

semantic-scholar-mcp-server

API 密钥（可选）

如需更高的速率限制和更好的性能：

1. 从 Semantic Scholar API 获取 API 密钥
2. 按照上文所示，在 FastMCP 配置的 env 部分添加该密钥

如果未提供 API 密钥，服务将以较低的速率限制进行未认证访问。

配置

参与贡献

请参阅 CONTRIBUTING.md。

环境变量

• SEMANTIC_SCHOLAR_API_KEY：你的 Semantic Scholar API 密钥（可选）
  • 从 Semantic Scholar API 获取密钥
  • 如果未提供，服务将以未认证方式访问

HTTP Bridge（内置）

此仓库包含一个小型 HTTP Bridge（semantic_scholar.bridge），可为常见工作流提供精简的 REST API。

默认监听端口：8000。

通过环境变量配置 Bridge：

• SEMANTIC_SCHOLAR_ENABLE_HTTP_BRIDGE（默认值：1）——设为 0 可禁用
• SEMANTIC_SCHOLAR_HTTP_BRIDGE_HOST（默认值：0.0.0.0）
• SEMANTIC_SCHOLAR_HTTP_BRIDGE_PORT（默认值：8000）

可用端点：

• GET /v1/paper/search?q=... ——论文搜索（参数：fields、offset、limit）
• GET /v1/paper/{paper_id} ——论文详情（参数：fields）
• POST /v1/paper/batch ——批量获取论文详情（JSON：{ "ids": [ ... ] }）
• GET /v1/author/search?q=... ——作者搜索（参数：fields、offset、limit）
• GET /v1/author/{author_id} ——作者详情（参数：fields）
• POST /v1/author/batch ——批量获取作者详情（JSON：{ "ids": [ ... ] }）
• GET /v1/recommendations?paper_id=... ——获取论文推荐

Bridge 复用此软件包的 HTTP 工具（semantic_scholar.utils.http）， 因此限流、API 密钥处理和连接池机制均与 MCP 工具保持一致。

示例：

curl 'http://localhost:8000/v1/paper/search?q=machine+learning&limit=5'

限流

服务会自动适配相应的限流规则：

使用 API 密钥时：

• 搜索、批量和推荐端点：每秒 1 个请求
• 其他端点：每秒 10 个请求

不使用 API 密钥时：

• 所有端点：每 5 分钟 100 个请求
• 请求超时时间更长

注意：限流规则可能会发生变化。最新信息请参阅 Semantic Scholar API。

Semantic Scholar API 条款

本项目使用 Allen Institute for AI（AI2）提供的 Semantic Scholar Academic Graph API。 使用前请阅读 API License Agreement。

可用的 MCP 工具

该服务目前提供 16 个 MCP 工具。

注意：所有工具均与官方 Semantic Scholar API 文档保持一致。字段规格详情及最新更新请参阅官方文档。

论文搜索工具

• paper_relevance_search：按相关性排名搜索论文

  • 支持全面的查询参数，包括年份范围和引用次数筛选条件
  • 返回分页结果，字段可自定义

• paper_bulk_search：支持排序选项的批量论文搜索

  • 与相关性搜索类似，但针对更大的结果集进行了优化
  • 支持按引用次数、发布日期等排序

• paper_title_search：按精确标题匹配查找论文

  • 已知标题时，可用于查找特定论文
  • 返回详细的论文信息，字段可自定义

• paper_details：获取特定论文的完整详情

  • 支持多种论文 ID 格式（S2 ID、DOI、ArXiv 等）
  • 返回详细的论文元数据，并支持嵌套字段

• paper_batch_details：高效获取多篇论文的详情

  • 每次请求最多接受 1000 个论文 ID
  • 支持与单篇论文详情相同的 ID 格式和字段

• paper_authors：获取特定论文的作者

  • 返回该论文的分页作者结果
  • 支持自定义作者字段，并可控制 offset 和 limit

• paper_autocomplete：根据部分查询内容获取论文标题建议

  • 返回精简的论文元数据，用于交互式搜索补全
  • 会将过长的查询截断至 API 支持的长度

• snippet_search：在论文片段和摘录中搜索

  • 返回标题、摘要和正文中的相关文本匹配结果
  • 支持按论文 ID、作者、出版物、年份和研究领域筛选

引用工具

• paper_citations：获取引用了特定论文的论文

  • 返回分页的引用论文列表
  • 提供可用的引用上下文
  • 支持自定义字段和排序

• paper_references：获取特定论文引用的论文

  • 返回分页的参考文献列表
  • 提供可用的参考文献上下文
  • 支持自定义字段和排序

作者工具

• author_search：按姓名搜索作者

  • 返回可自定义字段的分页结果
  • 包含所属机构和发表论文数量

• author_details：获取作者的详细信息

  • 返回全面的作者元数据
  • 包含 h 指数和引用次数等指标

• author_papers：获取作者撰写的论文

  • 返回分页的作者发表论文列表
  • 支持自定义字段和排序

• author_batch_details：获取多位作者的详细信息

  • 高效检索最多 1000 位作者的信息
  • 返回与单个作者详情相同的字段

推荐工具

• get_paper_recommendations_single：根据单篇论文获取推荐

  • 根据内容和引用模式推荐相似论文
  • 支持自定义推荐论文的字段

• get_paper_recommendations_multi：根据多篇论文获取推荐

  • 接受正面和负面示例论文
  • 返回与正面示例相似、与负面示例不同的论文

使用示例

基本论文搜索

results = await paper_relevance_search(
    context,
    query="machine learning",
    year="2020-2024",
    min_citation_count=50,
    fields=["title", "abstract", "authors"]
)

论文推荐

# Single paper recommendation
recommendations = await get_paper_recommendations_single(
    context,
    paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
    fields="title,authors,year"
)

# Multi-paper recommendation
recommendations = await get_paper_recommendations_multi(
    context,
    positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    negative_paper_ids=["ArXiv:1805.02262"],
    fields="title,abstract,authors"
)

批量操作

# Get details for multiple papers
papers = await paper_batch_details(
    context,
    paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    fields="title,authors,year,citations"
)

# Get details for multiple authors
authors = await author_batch_details(
    context,
    author_ids=["1741101", "1780531"],
    fields="name,hIndex,citationCount,paperCount"
)

错误处理

该服务提供标准化的错误响应：

{
    "error": {
        "type": "error_type",  # rate_limit, api_error, validation, timeout
        "message": "Error description",
        "details": {
            # Additional context
            "authenticated": true/false  # Indicates if request was authenticated
        }
    }
}