Semantic Scholar MCP Server

Semantic Scholar MCP Server

A 14-tool Semantic Scholar MCP server for academic research workflows. Direct access to 200M+ papers from Semantic Scholar — paper search, citation graph traversal, author profiles, and recommendations — from any Model Context Protocol client (e.g., Claude Desktop, Claude Code, Cursor, Cline, Continue, and others).

Every release ships verifiable supply-chain provenance: Sigstore-signed SLSA build-provenance attestations on the wheel, sdist, and container image; PEP 740 attestations on the PyPI upload; and a CycloneDX SBOM — so you can prove the artifact you installed was built from this repo. See Provenance & supply chain.

Author: Santiago Maniches · ORCID 0009-0005-6480-1987 · TOPOLOGICA LLC

Research authorship: Santiago Maniches independently directs and maintains this project and is the sole scientific author of its research contributions. AI-assisted tools have supported coding, documentation, and internal review; they do not constitute scientific coauthors or independent validation. Semantic Scholar content and reused software and methods are attributed to their respective sources.

Quick start

uvx s2-mcp-server                                      # run instantly, no install

claude mcp add semantic-scholar -- uvx s2-mcp-server # or register it in Claude Code

Runtime support (October 2026). Python 3.11–3.13 are the recommended, CI-tested interpreters. Python 3.10 reached upstream end of life on October 1, 2026 and no longer receives security fixes. The package retains Requires-Python >=3.10 and a legacy Python 3.10 compatibility test to avoid breaking existing installs, but Python 3.10 is not a security-supported runtime. Migrate deployed clients to Python 3.11 or newer. Python 3.14+ remains outside the declared CI verification matrix; installability is not a claim of tested support. The development dependency security audit runs on Python 3.12 and checks its hash-pinned closure, not every legacy environment.

No API key is needed to start. Set SEMANTIC_SCHOLAR_API_KEY to use your assigned Semantic Scholar quota and avoid the shared unauthenticated pool. Semantic Scholar currently assigns introductory API keys a 1 request/second limit across all endpoints. Claude Desktop, Docker, pip, and remote (Streamable HTTP) setups are in Installation.

Provenance & supply chain

A research tool is only as trustworthy as the chain from its source to the binary you run. Every release of this server ships cryptographically verifiable supply-chain evidence, all generated in CI from the tagged commit:

Verify the wheel and the container image against their attestations with the GitHub CLI:

# 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

The full supply-chain posture, including the known-limitations list, is in SECURITY.md. This is release-time provenance (proving how the artifact was built); the server does not currently attach a per-response receipt to individual API results.

How it compares

There is no public Semantic Scholar MCP standard, so the most useful comparison is against the obvious alternative: calling the Semantic Scholar REST API yourself from an agent. Everything in the right-hand column is plumbing this server already owns and the caller would otherwise reimplement.

Installation

Option 1: One-Line Install (Recommended)

# No cloning needed — runs directly from PyPI

uvx s2-mcp-server

Option 2: Claude Code

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

Option 3: Claude Desktop (Windows)

Add to %APPDATA%\Claude\claude_desktop_config.json:

{

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

Option 4: Claude Desktop (macOS)

Add to ~/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" } } } }

Option 5: pip / From Source

pip install s2-mcp-server

or

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

Option 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

Option 7: Remote server (Streamable HTTP) — requires ≥ 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

See [Remote access (Streamable HTTP)](#remote-access-streamable-http) for client

configuration, per-request API keys, and deployment guidance.

Note: An API key is optional for most public Semantic Scholar endpoints. This

server conservatively throttles unkeyed requests to about one per second,

but anonymous users share an upstream pool. Semantic Scholar can return HTTP

429 even when this server respects its local interval. For dependable,

sustained research workflows, configure an assigned API key.

See Known Limitations.

Architecture

flowchart LR

Client["MCP client (Claude Desktop, Claude Code, Cursor, Cline, Continue, …)"] subgraph Server ["s2-mcp-server (this package)"] direction TB FastMCP["FastMCP runtime (stdio / Streamable HTTP, lifespan)"] Tools["14 @mcp.tool functions (server.py)"] Models["Pydantic input models

• field sets (models.py)"] Validators["Paper-ID validator

(validators.py)"] Cache["TTL cache (cache.py)"] Fmt["Markdown formatters (formatters.py)"] HTTP["httpx client

• rate limit + retry/backoff

(client.py)"] Errors["Typed exceptions (errors.py)"] Log["Structured JSON logger (logging_config.py)"] end S2Graph["Semantic Scholar Graph API"] S2Recs["Semantic Scholar Recommendations API"]

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

Module responsibilities (src/semantic_scholar_mcp/):

| transport.py | Streamable