Semantic Scholar MCP Server

Semantic Scholar MCP 服务

面向学术研究工作流的 Semantic Scholar MCP 服务，提供 14 种工具。 可直接从 Semantic Scholar 访问 2 亿多篇论文，支持论文搜索、引文图遍历、作者档案和推荐，并可通过任何 Model Context Protocol 客户端使用（例如 Claude Desktop、Claude Code、Cursor、Cline、Continue 等）。

每次发布都附带可验证的供应链来源证明：对 wheel、sdist 和容器映像提供 Sigstore 签名的 SLSA 构建来源证明；在 PyPI 上传时提供 PEP 740 证明；并附有 CycloneDX SBOM，让你能够证明安装的制品是从此仓库构建的。详见来源证明与供应链。

作者：Santiago Maniches · ORCID 0009-0005-6480-1987 · TOPOLOGICA LLC

研究贡献署名： Santiago Maniches 独立指导并维护此项目，也是其研究贡献的唯一科学作者。AI 辅助工具曾用于支持编码、文档编写和内部审查；这些工具不属于科学合著者，也不构成独立验证。Semantic Scholar 内容以及复用的软件和方法均归于各自来源。

---

快速开始

uvx s2-mcp-server                                      # run instantly, no install
claude mcp add semantic-scholar -- uvx s2-mcp-server   # or register it in Claude Code

无需 API 密钥即可开始。设置 SEMANTIC_SCHOLAR_API_KEY，即可使用分配给你的 Semantic Scholar 配额，并避免使用共享的未认证请求池。目前，Semantic Scholar 为入门级 API 密钥分配的速率限制为所有端点合计每秒 1 个请求。Claude Desktop、Docker、pip 和远程（Streamable HTTP）配置请参阅安装。

---

来源与供应链

研究工具的可信度取决于从源代码到你运行的二进制文件的整个链路。此 MCP 服务的每个版本都会提供可通过密码学手段验证的供应链证据，所有证据均在 CI 中从已标记的提交生成：

保证	证明内容	生成位置
SLSA 构建来源证明（wheel + sdist）	已发布的分发包由此代码库的 publish.yml 从已发布标签构建，而非手动上传	publish.yml — actions/attest-build-provenance（build 作业）
SLSA 构建来源证明（容器镜像）	ghcr.io 镜像摘要由此代码库的 docker.yml 构建	docker.yml — actions/attest-build-provenance，push-to-registry（第 141–147 行）
PEP 740 证明	PyPI 上传本身通过 Trusted Publishing 携带由 Sigstore 支持的证明	publish.yml — attestations: true（publish-pypi 作业）
CycloneDX SBOM	机器可读的软件物料清单，由非特权作业根据确切 wheel 的静态解析依赖元数据生成（仅限 wheels，且不会执行其中任何内容），与该 wheel 的 SHA-256 绑定，随后仅针对该 wheel 进行证明	publish.yml — cyclonedx-py + scripts/release_sbom.py（sbom 作业）+ actions/attest-sbom（attest-sbom 作业）
固定到 SHA 的 Actions	每个 CI Action 都固定到一个提交 SHA，因此发布流水线本身不会在不知情的情况下发生变化	.github/workflows/ 中的所有作业（例如 publish.yml、docker.yml）

使用 GitHub CLI，根据证明验证 wheel 和容器镜像：

# Wheel / sdist (download from the PyPI project or the release assets first)
gh attestation verify s2_mcp_server-*.whl --repo smaniches/semantic-scholar-mcp

# Container image
gh attestation verify oci://ghcr.io/smaniches/semantic-scholar-mcp:latest \
  --repo smaniches/semantic-scholar-mcp

完整的供应链安全状况（包括已知限制清单）请参阅 SECURITY.md。这是发布时的来源证明（证明制品的构建方式）；目前，此 MCP 服务不会为单个 API 结果附加逐响应回执。

---

对比

目前没有公开的 Semantic Scholar MCP 标准，因此最有参考价值的对比对象是显而易见的替代方案：在 Agent 中自行调用 Semantic Scholar REST API。右侧一栏中的所有工作，此 MCP 服务都已负责处理；否则调用方就得自行重新实现。

	此 MCP 服务	Agent 直接调用 S2 REST API
工具接口	14 个类型化 MCP 工具（搜索、检索、推荐、状态）	调用方自行组合原始 HTTP 请求
引用图谱	get_paper 支持两个方向（引用和参考文献）	手动对两个端点分页
批量操作	单次调用可处理论文（≤500）和作者（≤1000）	调用方自行分批和分页
全文片段搜索	snippet_search 提供周边上下文	使用单独端点，由调用方自行组装
论文 ID 解析	七种格式——Semantic Scholar ID、DOI、ArXiv、PubMed、Corpus ID、ACL、URL——并在请求前验证 (validators.py)	调用方自行规范化并验证 ID
速率限制	客户端限流器，采用保守且兼容 S2 的默认认证配额，并支持配置分配的配额 (client.py)	调用方手动限流
重试 / 退避	遇到 429/502/503/超时错误时进行有界、带抖动的重试，并遵循 Retry-After (client.py)	调用方自行实现重试
错误	类型化异常层级，可由调用方分支处理 (errors.py)	解析 HTTP 状态字符串
输出	每次调用可选择适合聊天的 Markdown 或 JSON (formatters.py)	原始 JSON
供应链来源证明	每个版本均提供 SLSA + PEP 740 + CycloneDX SBOM（见上文）	不适用
可引用性	已申请 Zenodo DOI，采用 MIT 许可证	不适用

---

安装

选项 1：一行安装（推荐）

# No cloning needed — runs directly from PyPI
uvx s2-mcp-server

选项 2：Claude Code

claude mcp add semantic-scholar -- uvx s2-mcp-server

选项 3：Claude Desktop（Windows）

添加到 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["s2-mcp-server"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
      }
    }
  }
}

选项 4：Claude Desktop（macOS）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["s2-mcp-server"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
      }
    }
  }
}

选项 5：pip / 从源代码安装

pip install s2-mcp-server
# or
git clone https://github.com/smaniches/semantic-scholar-mcp.git
cd semantic-scholar-mcp && pip install -e .

选项 6：Docker

docker pull ghcr.io/smaniches/semantic-scholar-mcp:latest
docker run -e SEMANTIC_SCHOLAR_API_KEY=your-key ghcr.io/smaniches/semantic-scholar-mcp

选项 7：远程服务（Streamable HTTP）——需要 ≥ 1.5.0

# Serve MCP over HTTP at http://127.0.0.1:8000/mcp instead of stdio
# (--from pins the floor: uvx may otherwise reuse a cached older version)
uvx --from "s2-mcp-server>=1.5.0" s2-mcp-server --transport http

有关客户端配置、每个请求的 API 密钥和部署指南，请参阅远程访问（Streamable HTTP）。

注意： 大多数公开的 Semantic Scholar 端点都不需要 API 密钥。此服务会对未提供密钥的请求进行保守限流，约每秒一次，但匿名用户共享上游请求池。即使此服务遵守本地间隔，Semantic Scholar 仍可能返回 HTTP 429。若要可靠地持续运行研究工作流，请配置分配给你的 API 密钥。 请参阅已知限制。

---

架构

flowchart LR
  Client["MCP client<br/>(Claude Desktop, Claude Code,<br/>Cursor, Cline, Continue, …)"]
  subgraph Server ["s2-mcp-server (this package)"]
    direction TB
    FastMCP["FastMCP runtime<br/>(stdio / Streamable HTTP, lifespan)"]
    Tools["14 @mcp.tool functions<br/>(server.py)"]
    Models["Pydantic input models<br/>+ field sets (models.py)"]
    Validators["Paper-ID validator<br/>(validators.py)"]
    Cache["TTL cache<br/>(cache.py)"]
    Fmt["Markdown formatters<br/>(formatters.py)"]
    HTTP["httpx client<br/>+ rate limit + retry/backoff<br/>(client.py)"]
    Errors["Typed exceptions<br/>(errors.py)"]
    Log["Structured JSON logger<br/>(logging_config.py)"]
  end
  S2Graph["Semantic Scholar<br/>Graph API"]
  S2Recs["Semantic Scholar<br/>Recommendations API"]

  Client <-- "stdio or Streamable HTTP<br/>(JSON-RPC)" --> FastMCP
  FastMCP --> Tools
  Tools --> Models
  Tools --> Validators
  Tools --> Cache
  Tools --> HTTP
  Tools --> Fmt
  HTTP --> Errors
  HTTP --> Log
  HTTP -- "GET / POST<br/>x-api-key" --> S2Graph
  HTTP -- "GET / POST<br/>x-api-key" --> S2Recs

模块职责（src/semantic_scholar_mcp/）：

模块	职责
server.py	FastMCP 实例、14 个 @mcp.tool 注册项、生命周期和 main() 入口。重新导出辅助函数接口，以保持向后兼容。
transport.py	Streamable HTTP 传输：CLI/环境变量解析（--transport http）、uvicorn 接线，以及将每个请求的 API 密钥（标头 / 查询参数 / Smithery 配置）提取到请求范围的 contextvar 中。
client.py	共享的 httpx.AsyncClient 单例、客户端限流器（公共配额默认 1.0 秒；已认证配额默认 1.1 秒，可根据分配的配额进行配置）、遇到 429/502/503/超时时采用指数退避加抖动的重试循环，以及 HTTP 到类型化异常的映射。
models.py	每个工具对应的 Pydantic 输入模型、ResponseFormat 枚举、分层论文字段集常量（PAPER_SEARCH_FIELDS、…_LITE、PAPER_BULK_SEARCH_FIELDS、PAPER_DETAIL_FIELDS）以及 AUTHOR_FIELDS。
validators.py	论文 ID 的预检验证。拒绝 NUL 字节、?、# 和路径遍历；接受七种规范 ID 格式。
cache.py	会话内用于论文/作者查询的内存 TTL 缓存（5 分钟，200 条目，优先淘汰最旧条目）。
formatters.py	论文和作者字典的 Markdown 渲染器，针对聊天界面的可读性进行了优化。
errors.py	SemanticScholarError 异常层级：AuthenticationError、RateLimitError、NotFoundError、ValidationError、ServerError。
logging_config.py	在 stderr 上使用每行一个 JSON 对象的 StructuredFormatter；可安全地接入任何日志聚合器。

值得了解的设计选择

• 每个进程仅使用一个 httpx.AsyncClient。 该客户端按需创建，并在 FastMCP 生命周期结束时关闭。这样可分摊连接建立开销，并遵守 keep-alive 限制。生命周期采用引用计数：在 Streamable HTTP 传输下，SDK 会为每个请求进入该生命周期，因此只有最后一个持有者退出时才会执行清理。
• 限流由客户端实施，而非 API。 信号量和上次请求时间戳可确保即使 MCP 主机并行调用工具，也不会超过各层级的请求间隔。
• 重试次数有限，并带随机抖动。 最多重试 MAX_RETRIES = 3 次，基础间隔为 1 秒，上限为 30 秒。若存在 Retry-After，则遵循其值。
• 错误经过类型化处理。 状态码会映射到一组精简的异常层级，因此调用方可以根据 AuthenticationError、RateLimitError 或 NotFoundError 进行分支处理，而无需解析字符串。
• 输入会进行预检验证。 论文 ID 会在发送任何出站请求前检查；无效 ID 不会发送到网络。
• 版本只有一个来源。 __version__ 根据 importlib.metadata.version("s2-mcp-server") 获取，因此只需更新 pyproject.toml；每次发布时，release-please 会同步更新清单、server.json（2 个路径）、CITATION.cff 和 .zenodo.json。

---

配置

API 密钥选项

你可以通过以下三种方式提供 API 密钥：

1. 环境变量（推荐用于持久使用）：

   export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"
   

2. 每个请求的 HTTP 标头（仅限 Streamable HTTP 传输）：每次请求都发送 x-api-key: your-key — 参见 远程访问（Streamable HTTP）。

3. 每个请求的参数（优先于环境变量）：

   {
     "api_key": "your-api-key-here"
   }
   

   **已弃用：**每个请求中的 api_key 已弃用，并将在 v2.0.0 中移除。工具调用参数可能会显示在 MCP 记录、客户端日志和大模型的工具调用历史中。请改用 SEMANTIC_SCHOLAR_API_KEY 环境变量。详情请参见 SECURITY.md。

在此获取免费的 API 密钥：https://www.semanticscholar.org/product/api

Claude Desktop 设置

将以下内容添加到 Claude Desktop 配置文件：

Windows： %APPDATA%\Claude\claude_desktop_config.json macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "python",
      "args": ["-m", "semantic_scholar_mcp"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
      }
    }
  }
}

然后重启 Claude Desktop。

---

远程访问（Streamable HTTP）

stdio 仍是默认传输方式。--transport http 会通过 MCP Streamable HTTP 传输提供相同的 14 个工具，远程客户端（如 claude.ai 自定义连接器、Smithery 列表、mcp-remote 桥接程序）会连接到该传输。

**需要 s2-mcp-server ≥ 1.5.0。**较早的版本（≤ 1.4.0）不会解析 CLI 标志：它们会静默忽略 --transport http，转而启动 stdio 服务，且不会打开端口。

# Local HTTP endpoint at http://127.0.0.1:8000/mcp
# (--from pins the floor: uvx may otherwise reuse a cached older version)
uvx --from "s2-mcp-server>=1.5.0" s2-mcp-server --transport http

# Bind a public interface and custom port (only behind a TLS proxy — see Security).
# The DNS-rebinding guard only admits localhost Host headers by default, so
# also allow the public hostname clients will use (":*" matches any port).
uvx --from "s2-mcp-server>=1.7.1" s2-mcp-server --transport http --host 0.0.0.0 --port 8080 \
  --allowed-host "mcp.example.org:*"

# Docker
docker run -p 8000:8000 ghcr.io/smaniches/semantic-scholar-mcp --transport http

标志和环境变量

标志	环境变量	默认值	含义
--transport	MCP_TRANSPORT	stdio	stdio、http（别名：streamable-http）
--host	MCP_HOST	127.0.0.1	绑定地址（Docker 镜像中为 0.0.0.0）
--port	MCP_PORT，然后是 PORT	8000	绑定端口（托管平台会使用 PORT）
--path	MCP_PATH	/mcp	MCP 端点的 URL 路径
--allowed-host（可重复）	MCP_ALLOWED_HOSTS（逗号分隔）	仅 localhost	DNS 重绑定防护允许的额外 Host 标头值，例如 mcp.example.org:*（≥ 1.7.1）
--allowed-origin（可重复）	MCP_ALLOWED_ORIGINS（逗号分隔）	仅 localhost	DNS 重绑定防护允许的额外 Origin 标头值，例如 https://mcp.example.org（≥ 1.7.1）
--version	—	—	输出软件包版本并退出
—	MCP_STATELESS_HTTP	true	每个请求对应一次独立的服务交互（推荐）
—	MCP_JSON_RESPONSE	true	使用纯 JSON 响应，而不是 SSE 流

CLI 标志优先于环境变量。服务默认采用无状态模式并返回 JSON，这是生产环境部署 Streamable HTTP 的推荐配置；且没有工具依赖会话、流式传输或服务端发起的消息，因此不会带来功能上的取舍。

每个请求的 API 密钥（使用你自己的密钥）

通过 HTTP 提供服务时，每个请求都可以携带自己的 Semantic Scholar API 密钥；并发用户不会共享或看到彼此的密钥。来源按优先级排序如下：

1. x-api-key HTTP 标头（推荐）
2. SEMANTIC_SCHOLAR_API_KEY 查询参数（Smithery 会话配置）
3. api_key 查询参数
4. 旧版 base64 ?config= 参数（较早的 Smithery 部署）

未携带密钥的请求会回退使用服务的 SEMANTIC_SCHOLAR_API_KEY 环境变量，或使用无需密钥的公共层级访问。

客户端配置

Claude Code

claude mcp add --transport http semantic-scholar http://127.0.0.1:8000/mcp \
  --header "x-api-key: your-key-here"

JSON 配置（接受 url 的客户端）

{
  "mcpServers": {
    "semantic-scholar": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

claude.ai 自定义连接器需要公开的 HTTPS URL，并且只接受无需身份验证的服务或 OAuth——claude.ai 不支持在连接器 URL 中使用 API 密钥。请在服务端提供密钥（SEMANTIC_SCHOLAR_API_KEY 环境变量）来托管服务，并将公开的 /mcp URL 注册为连接器。

Smithery 通过 URL 列出远程服务（smithery mcp publish <url>）；上述按请求提取密钥的方式开箱即兼容 Smithery 会话配置。

安全说明

• HTTP 传输不会对传入调用方进行身份验证。默认绑定地址为环回地址（127.0.0.1）。只有在 TLS 终止反向代理后，才应将其公开到互联网；并且优先使用 x-api-key 标头，而非查询参数（URL 最终会出现在访问日志中）。
• API 密钥仅在单个请求范围内有效，服务本身绝不会记录这些密钥。（如上所述，放在 URL 查询参数中的密钥仍可能出现在访问日志中——请优先使用 x-api-key 标头。）
• 有关该项目更全面的威胁模型，请参阅 SECURITY.md。

---

支持的 ID 格式

服务接受以下论文标识符格式：

格式	模式	示例
Semantic Scholar ID	40 位十六进制字符	649def34f8be52c8b66281af98ae884c09aef38b
DOI	DOI:xxx	DOI:10.1038/s41586-021-03819-2
ArXiv	ARXIV:xxx	ARXIV:2106.15928 或 ARXIV:2106.15928v2
PubMed	PMID:xxx	PMID:32908142
Corpus ID	CorpusId:xxx	CorpusId:215416146
ACL	ACL:xxx	ACL:P19-1285
URL	URL:xxx	URL:https://arxiv.org/abs/2106.15928

---

工具参考

1. semantic_scholar_search_papers

使用高级筛选条件搜索学术论文。

参数：

参数	类型	必填	描述
query	string	是	纯文本搜索查询，按原样发送（此端点未记录特殊语法；如需布尔/短语语法，请使用 semantic_scholar_bulk_search）
year	string	否	年份筛选条件："2024"、"2020-2024" 或 "2020-"
fields_of_study	string[]	否	按领域筛选：["Computer Science", "Biology"]
publication_types	string[]	否	按类型筛选：["Review", "JournalArticle"]
open_access_only	boolean	否	仅返回开放获取论文（默认值：false）
min_citation_count	integer	否	最低引用次数
limit	integer	否	最大结果数，范围为 1-100（默认值：10）
offset	integer	否	分页偏移量（默认值：0）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

示例：

Search for "transformer attention mechanism" papers from 2023 with at least 100 citations

JSON 示例：

{
  "query": "transformer attention mechanism",
  "year": "2023",
  "min_citation_count": 100,
  "fields_of_study": ["Computer Science"],
  "limit": 20
}

---

2. semantic_scholar_get_paper

获取特定论文的详细信息。

参数：

参数	类型	必填	描述
paper_id	string	是	任意受支持格式的论文 ID
include_citations	boolean	否	是否包含引用该论文的论文（默认值：false）
include_references	boolean	否	是否包含该论文引用的论文（默认值：false）
citations_limit	integer	否	每页最多返回的引用该论文的论文数，范围为 1-100（默认值：10）
citations_offset	integer	否	引用该论文的论文列表的偏移量（默认值：0）
references_limit	integer	否	每页最多返回的该论文引用的论文数，范围为 1-100（默认值：10）
references_offset	integer	否	该论文引用的论文列表的偏移量（默认值：0）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

示例：

Get details for DOI:10.1038/s41586-021-03819-2 including its top 20 citations

JSON 示例：

{
  "paper_id": "DOI:10.1038/s41586-021-03819-2",
  "include_citations": true,
  "citations_limit": 20,
  "citations_offset": 0,
  "response_format": "json"
}

引用列表和参考文献列表的分页相互独立。在 JSON 模式下，指定的方向会保留现有的 citations / references 数组，并额外返回包含 offset 和 next 的 citations_page / references_page 元数据。 当 next 不为 null 时，在下一次调用中将其用作该方向的 *_offset，并保持论文 ID 和 limit 不变。next 为 null 表示 Semantic Scholar 未提供后续页信息。Markdown 模式会在有后续页时显示续页提示。切勿将第一页视为完整的引用关系图。

---

3. semantic_scholar_search_authors

按姓名搜索学术作者。

参数：

参数	类型	必填	描述
query	string	是	要搜索的作者姓名
limit	integer	否	最多返回的结果数，范围为 1-100（默认值：10）
offset	integer	否	分页偏移量（默认值：0）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

示例：

Find author "Yoshua Bengio"

JSON 示例：

{
  "query": "Yoshua Bengio",
  "limit": 5
}

---

4. semantic_scholar_get_author

获取包含发表论文信息的作者简介。

参数：

参数	类型	必填	描述
author_id	string	是	Semantic Scholar 作者 ID
include_papers	boolean	否	是否包含发表的论文（默认值：true）
papers_limit	integer	否	最多返回的论文数，范围为 1-100（默认值：20）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

示例：

Get author profile for author ID 1741101 with their top 50 publications

JSON 示例：

{
  "author_id": "1741101",
  "include_papers": true,
  "papers_limit": 50
}

---

5. semantic_scholar_recommendations

根据种子论文获取 AI 驱动的论文推荐。

参数：

参数	类型	必填	描述
paper_id	string	是	任意受支持格式的种子论文 ID
from_pool	string	否	推荐论文池："recent"（默认值）或 "all-cs"
limit	integer	否	最多返回的推荐数，范围为 1-100（默认值：10）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

示例：

Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38b

JSON 示例：

{
  "paper_id": "ARXIV:1706.03762",
  "limit": 15
}

---

6. semantic_scholar_bulk_papers

在单个请求中检索多篇论文（最多 500 篇）。

参数：

参数	类型	必填	描述
paper_ids	string[]	是	论文 ID 列表（最多 500 个）
response_format	string	否	"markdown" 或 "json"（默认值：json）
api_key	string	否	覆盖环境 API 密钥

示例：

Retrieve these papers: DOI:10.1038/nature12373, ARXIV:2106.15928, PMID:32908142

JSON 示例：

{
  "paper_ids": [
    "DOI:10.1038/nature12373",
    "ARXIV:2106.15928",
    "PMID:32908142"
  ]
}

---

7. semantic_scholar_bulk_search

搜索论文，支持排序和基于游标的大型结果集分页。 与 search_papers 不同，此工具支持 sort 排序顺序，并返回用于 遍历所有结果的 token。

参数：

参数	类型	必需	描述
query	string	是	搜索查询；支持 +（AND）、|（OR）、-（NOT）、"phrase"、* 前缀、( ) 分组
sort	string	否	排序顺序，例如 "citationCount:desc"、"publicationDate:asc"
token	string	否	上一次 bulk_search 响应中的续传令牌
year	string	否	年份筛选条件："2024"、"2020-2024"、"2020-"
fields_of_study	string[]	否	按领域筛选：["Computer Science"]
publication_types	string[]	否	按类型筛选：["Review", "JournalArticle"]
min_citation_count	integer	否	最低引用次数
limit	integer	否	请求的分页大小，为 1-1000（默认值：100）。会转发此参数，但据观察，API 会忽略它，每页最多返回 1000 篇论文；完整页面及其 token 会原样返回
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境变量中的 API 密钥

JSON 示例：

{
  "query": "graph neural networks",
  "sort": "citationCount:desc",
  "year": "2020-2024",
  "limit": 100
}

**返回：**结果总数、当前页的论文，以及用于获取下一页的 token（如果还有更多结果）。

---

8. semantic_scholar_export_citation

以 BibTeX 格式导出论文引用。

参数：

参数	类型	必需	描述
paper_id	string	是	任意受支持格式的论文 ID
format	string	否	引用格式（目前仅支持 "bibtex"）
api_key	string	否	覆盖环境变量中的 API 密钥

JSON 示例：

{
  "paper_id": "DOI:10.1038/s41586-021-03819-2",
  "format": "bibtex"
}

**返回：**所请求论文的 BibTeX 字符串。

---

9. semantic_scholar_match_paper

查找与标题字符串最匹配的单篇论文。除匹配到的论文外，还会返回数值型 matchScore。

参数：

参数	类型	必需	描述
query	string	是	要匹配的论文标题（1-500 个字符）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境变量中的 API 密钥

JSON 示例：

{
  "query": "Attention Is All You Need"
}

**返回：**最匹配的论文及其 matchScore；如果没有匹配项，则返回“No matching paper found.”。

---

10. semantic_scholar_paper_authors

获取论文作者的完整资料（比 get_paper 返回的简略作者列表更丰富）。

参数：

参数	类型	必需	描述
paper_id	string	是	任意受支持格式的论文 ID
limit	integer	否	返回的作者数量上限，为 1-1000（默认值：100）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境变量中的 API 密钥

JSON 示例：

{
  "paper_id": "ARXIV:1706.03762",
  "limit": 25
}

**返回：**论文作者的完整资料列表。

---

11. semantic_scholar_author_batch

在单个请求中检索多位作者（最多 1000 位）。

参数：

参数	类型	必需	描述
author_ids	string[]	是	作者 ID 列表（1-1000 个）
response_format	string	否	"markdown" 或 "json"（默认值：json）
api_key	string	否	覆盖环境变量中的 API 密钥

JSON 示例：

{
  "author_ids": ["1741101", "40348417", "144749327"]
}

返回：requested / retrieved 的数量、检索到的作者资料，以及 API 未返回的 ID 所组成的 not_found 列表。

---

12. semantic_scholar_multi_recommend

使用多个正例论文（可选负例论文）获取推荐。

参数：

参数	类型	必填	描述
positive_paper_ids	string[]	是	查找相似结果的论文（1-100 篇）
negative_paper_ids	string[]	否	希望推荐结果避开的论文（0-100 篇）
limit	integer	否	推荐数量上限：1-500（默认值：10）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

JSON 示例：

{
  "positive_paper_ids": ["ARXIV:1706.03762", "ARXIV:1810.04805"],
  "negative_paper_ids": ["DOI:10.1038/nature14539"],
  "limit": 20
}

**返回：**推荐的论文，以及所用正例／负例种子的回显。

---

13. semantic_scholar_snippet_search

在论文全文中搜索，并返回带有上下文的文本片段。没有 API 密钥时，速率限制非常严格。

参数：

参数	类型	必填	描述
query	string	是	论文文本搜索查询（1-500 个字符）
paper_ids	string[]	否	将搜索范围限制为指定论文（最多 100 篇）
year	string	否	年份筛选："2024"、"2020-2024"、"2020-"
fields_of_study	string[]	否	按学科筛选：["Computer Science"]
min_citation_count	integer	否	最低引用次数
limit	integer	否	结果数量上限：1-100（默认值：10）
response_format	string	否	"markdown" 或 "json"（默认值：markdown）
api_key	string	否	覆盖环境 API 密钥

JSON 示例：

{
  "query": "scaling laws for language models",
  "year": "2022-2024",
  "limit": 20
}

**返回：**匹配的片段，每个片段都包含来源论文标题、章节和简短的文本摘录。

---

14. semantic_scholar_status

检查服务健康状况和 API 连通状态。

**参数：**无

示例：

Check Semantic Scholar API status

响应：

{
  "server": "semantic-scholar-mcp",
  "version": "<current package version>",
  "api_key_configured": true,
  "rate_tier": "authenticated",
  "configuration_valid": true,
  "min_seconds_between_requests": 1.1,
  "effective_client_max_requests_per_second": 0.909091,
  "timestamp": "2026-04-06T12:00:00.000000+00:00",
  "api_reachable": true,
  "rate_limited": false,
  "retry_after": null
}

---

速率限制

Semantic Scholar 当前的 API 指南指出，入门级 API 密钥在所有端点上的请求速率为 每秒 1 次；部分密钥经审核后可能获得更高的速率。未经身份验证的请求共享上游容量，在高负载期间可能受到限流。

因此，服务采用以下保守的客户端默认值：

访问方式	客户端最小间隔	客户端有效最大速率
无 API 密钥	1.0 秒	1 次请求/秒
有 API 密钥	1.1 秒	约 0.91 次请求/秒

如果 Semantic Scholar 已明确为你的密钥分配了不同的配额，请将 SEMANTIC_SCHOLAR_MIN_SECONDS_BETWEEN_REQUESTS 设为一个低于该上限的间隔。例如，经审核的 10 RPS 配额应使用略大于 0.1 秒的间隔，而不是假设每个 API 密钥都具有该速率。此设置对整个进程生效，因此接受多个用户自带密钥的远程部署应根据所接受配额中最慢的速率进行配置。

服务会自动处理速率限制，包括：

• 串行化请求以确保满足最小间隔
• 对 429（速率限制）、502（网关错误）和 503（服务不可用）错误进行指数退避重试
• 最多重试 3 次，并加入随机抖动

---

开发

# Clone
git clone https://github.com/smaniches/semantic-scholar-mcp.git
cd semantic-scholar-mcp

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/semantic_scholar_mcp --cov-report=term-missing

# Type checking
mypy src/

---

安全性

服务器不会将 API 密钥持久化到磁盘。当服务器发出经过身份验证的请求时，密钥仅会通过 HTTPS 以 x-api-key 标头的形式发送至 api.semanticscholar.org。不会向任何第三方发送遥测数据。使用默认的 stdio 传输时，服务器会在你的机器上本地运行；如果你通过 Streamable HTTP 连接到托管在远程的实例，你的单次请求密钥也会经过该端点的运营方，然后才转发给 Semantic Scholar — 仅向你信任的远程端点发送密钥，并且仅通过 HTTPS 发送。

请优先使用 SEMANTIC_SCHOLAR_API_KEY 环境变量，而不是单次请求的 api_key 工具参数。单次请求参数已弃用（计划在 v2.0.0 中移除），因为工具调用参数可能会显示在 MCP 对话记录和客户端日志中。有关漏洞报告和已知限制列表，请参阅 SECURITY.md。

---

同一作者的相关 MCP 服务

• alphafold-sovereign-mcp — 用于 AlphaFold DB 和其他公共生物医学数据源的 Model Context Protocol 服务，带有本地 SQLite 知识图谱（pip install alphafold-sovereign-mcp）。
• uniprot-mcp — 用于 UniProt Swiss-Prot 和 TrEMBL 的 Model Context Protocol 服务（pip install uniprot-mcp-server）。

---

许可证

MIT 许可证 — 请参阅 LICENSE 文件。

---

作者

Santiago Maniches

• 创始人兼 CEO，TOPOLOGICA LLC
• ORCID：0009-0005-6480-1987
• LinkedIn：santiago-maniches
• 网站：topologica.ai

---

贡献

欢迎贡献！请阅读我们的贡献指南。

---

支持

• 问题：GitHub Issues
• 联系方式：[email protected]

---

由 TOPOLOGICA LLC 构建