Semantic Scholar MCP 服务器

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

项目结构

该项目已被重构为模块化结构，以提高可维护性：

semantic-scholar-server/
├── semantic_scholar/            # 主包
│   ├── __init__.py             # 包初始化
│   ├── server.py               # 服务器设置和主要功能
│   ├── mcp.py                  # 集中式 FastMCP 实例定义
│   ├── config.py               # 配置类
│   ├── utils/                  # 实用工具模块
│   │   ├── __init__.py
│   │   ├── errors.py           # 错误处理
│   │   └── http.py             # HTTP 客户端和速率限制
│   ├── api/                    # API 端点
│       ├── __init__.py
│       ├── papers.py           # 论文相关端点
│       ├── authors.py          # 作者相关端点
│       └── recommendations.py  # 推荐端点
├── run.py                      # 入口点脚本

此结构：

• 将关注点分离到逻辑模块中
• 使代码库更易于理解和维护
• 允许更好的测试和未来的扩展
• 将相关功能分组在一起
• 集中 FastMCP 实例以避免循环导入

特性

• 论文搜索与发现

  • 具有高级过滤器的全文搜索
  • 基于标题的论文匹配
  • 论文推荐（单篇和多篇）
  • 批量论文详情检索
  • 具有排名策略的高级搜索

• 引文分析

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

• 作者信息

  • 作者搜索和个人资料详情
  • 发表历史
  • 批量作者详情检索

• 高级特性

  • 具有多种排名策略的复杂搜索
  • 可定制的字段选择
  • 高效的批量操作
  • 符合速率限制
  • 支持经过身份验证和未经身份验证的访问
  • 优雅的关闭和错误处理
  • 连接池和资源管理

系统要求

• Python 3.8+
• FastMCP 框架
• API 密钥的环境变量（可选）

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Semantic Scholar MCP Server：

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-server

2. 按照以下步骤安装 FastMCP 和其他依赖项：https://github.com/jlowin/fastmcp

3. 配置 FastMCP：

对于 Claude Desktop 用户，您需要在 FastMCP 配置文件中配置服务器。 将以下内容添加到您的配置中（通常在 ~/.config/claude-desktop/config.json 中）：

{
  "mcps": {
    "Semantic Scholar Server": {
      "command": "/path/to/your/venv/bin/fastmcp",
      "args": [
        "run",
        "/path/to/your/semantic-scholar-server/run.py"
      ],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"  # 可选
      }
    }
  }
}

请务必：

• 将 /path/to/your/venv/bin/fastmcp 替换为 FastMCP 安装的实际路径
• 将 /path/to/your/semantic-scholar-server/run.py 替换为您机器上 run.py 的实际路径
• 如果您有 Semantic Scholar API 密钥，请将其添加到 env 部分。 如果没有，您可以完全删除 env 部分

4. 开始使用服务器：

该服务器现在可用于您的 Claude Desktop 实例。 无需手动运行任何命令 - Claude 会在需要时自动启动和管理服务器进程。

API 密钥（可选）

要获得更高的速率限制和更好的性能：

1. 从 Semantic Scholar API 获取 API 密钥
2. 如上所示，将其添加到 FastMCP 配置的 env 部分

如果未提供 API 密钥，服务器将使用未经身份验证的访问，速率限制较低。

配置

环境变量

• SEMANTIC_SCHOLAR_API_KEY: 您的 Semantic Scholar API 密钥（可选）
  • 从 Semantic Scholar API 获取您的密钥
  • 如果未提供，服务器将使用未经身份验证的访问

速率限制

服务器会自动调整到适当的速率限制：

使用 API 密钥:

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

不使用 API 密钥:

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

可用的 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_citations: 获取引用特定论文的论文

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

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

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

作者工具

• author_search: 按姓名搜索作者

  • 返回带有可自定义字段的分页结果
  • 包括隶属关系和发表计数

• author_details: 获取有关作者的详细信息

  • 返回全面的作者元数据
  • 包括 h 指数和引文计数等指标

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

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

• author_batch_details: 获取多个作者的详细信息

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

推荐工具

• paper_recommendations_single: 根据单篇论文获取推荐

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

• paper_recommendations_multi: 根据多篇论文获取推荐

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

使用示例

基本论文搜索

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

论文推荐

# 单篇论文推荐
recommendations = await paper_recommendations_single(
    context,
    paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
    fields="title,authors,year"
)

# 多篇论文推荐
recommendations = await paper_recommendations_multi(
    context,
    positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    negative_paper_ids=["ArXiv:1805.02262"],
    fields="title,abstract,authors"
)

批量操作

# 获取多个论文的详细信息
papers = await paper_batch_details(
    context,
    paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    fields="title,authors,year,citations"
)

# 获取多个作者的详细信息
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  # 指示请求是否经过身份验证
        }
    }
}