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 服务器，请运行以下命令：

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

手动安装

1. 克隆仓库：

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

1. 按照 FastMCP GitHub 页面 的说明安装 FastMCP 和其他依赖项。

2. 配置 FastMCP：

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

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 部分。

1. 开始使用服务器：

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

API 密钥（可选）

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

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

如果未提供 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-index 和引用次数等指标

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

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

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

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

推荐工具

• paper_recommendations_single：基于单篇论文获取推荐

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

• paper_recommendations_multi：基于多篇论文获取推荐

  • 接受正例和反例论文- 返回与正面示例相似但与负面示例不相似的论文

使用示例

基本文献搜索

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

论文推荐

python

单篇论文推荐

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"
)

批量操作

python

获取多篇论文的详细信息

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"
)

错误处理

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

python
{
"error": {
"type": "error_type", # rate_limit, api_error, validation, timeout
"message": "错误描述",
"details": {
# 额外上下文
"authenticated": true/false # 表示请求是否已认证
}
}
}