Skip to main content
Glama
Semantic Scholar MCP Server

Semantic Scholar MCP Server

Semantic Scholar MCP Server

CI codecov PyPI version PyPI downloads/30d DOI Provenance: SLSA + SBOM Docker GitHub Release License: MIT MCP Python 3.11-3.13 recommended Glama score Awesome MCP Servers

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.


Related MCP server: Semantic Scholar MCP Server

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:

Guarantee

What it proves

Where it is produced

SLSA build provenance (wheel + sdist)

the published distributions were built by this repo's publish.yml from the released tag, not hand-uploaded

publish.yml — actions/attest-build-provenance (build job)

SLSA build provenance (container image)

the ghcr.io image digest was built by this repo's docker.yml

docker.yml — actions/attest-build-provenance, push-to-registry (lines 141–147)

PEP 740 attestations

the PyPI upload itself carries Sigstore-backed attestations under Trusted Publishing

publish.yml — attestations: true (publish-pypi job)

CycloneDX SBOM

a machine-readable bill of materials, generated in an unprivileged job from the exact wheel's statically resolved dependency metadata (wheels only, none of it executed), SHA-256-bound to that wheel, then attested against the wheel alone

publish.yml — cyclonedx-py + scripts/release_sbom.py (sbom job) + actions/attest-sbom (attest-sbom job)

SHA-pinned Actions

every CI action is pinned to a commit SHA, so the release pipeline itself cannot silently change

all jobs in .github/workflows/ (e.g. publish.yml, docker.yml)

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.

This server

Raw S2 REST API from an agent

Tool surface

14 typed MCP tools (search, retrieval, recommendations, status)

caller composes raw HTTP requests

Citation graph

both directions (citations and references) in get_paper

manual paging over two endpoints

Bulk operations

papers (≤500) and authors (≤1000) in one call

caller batches and paginates

Full-text snippet search

snippet_search with surrounding context

separate endpoint, caller-assembled

Paper-ID resolution

seven formats — Semantic Scholar ID, DOI, ArXiv, PubMed, Corpus ID, ACL, URL — validated pre-flight (validators.py)

caller normalizes and validates IDs

Rate limiting

client-side limiter with a conservative S2-compatible authenticated default and configurable assigned quota (client.py)

caller throttles by hand

Retry / backoff

bounded, jittered retry on 429/502/503/timeout, honors Retry-After (client.py)

caller implements retry

Errors

typed exception hierarchy, branchable by caller (errors.py)

parse HTTP status strings

Output

chat-tuned Markdown or JSON per call (formatters.py)

raw JSON

Supply-chain provenance

SLSA + PEP 740 + CycloneDX SBOM per release (see above)

n/a

Citability

minted Zenodo DOI, MIT licensed

n/a


Installation

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

Module responsibilities (src/semantic_scholar_mcp/):

Module

Responsibility

server.py

FastMCP instance, 14 @mcp.tool registrations, lifespan, main() entry. Re-exports the helper surface for back-compat.

transport.py

Streamable HTTP transport: CLI/env parsing (--transport http), uvicorn wiring, and per-request API-key extraction (header / query param / Smithery config) into a request-scoped contextvar.

client.py

Shared httpx.AsyncClient singleton, client-side rate limiter (1.0 s public; 1.1 s authenticated default, configurable for assigned quotas), retry loop with exponential backoff + jitter on 429/502/503/timeout, HTTP→typed-exception mapping.

models.py

Pydantic input models per tool, ResponseFormat enum, the tiered paper field-set constants (PAPER_SEARCH_FIELDS, …_LITE, PAPER_BULK_SEARCH_FIELDS, PAPER_DETAIL_FIELDS) plus AUTHOR_FIELDS.

validators.py

Pre-flight paper-ID validation. Rejects NUL bytes, ?, #, path traversal; accepts the seven canonical ID formats.

cache.py

In-memory TTL cache (5 min, 200 entries, oldest-first eviction) for paper/author lookups within a session.

formatters.py

Markdown renderers for paper and author dicts, tuned for chat-surface readability.

errors.py

SemanticScholarError hierarchy: AuthenticationError, RateLimitError, NotFoundError, ValidationError, ServerError.

logging_config.py

One-JSON-per-line StructuredFormatter on stderr; safe to ship through any log aggregator.

Design choices worth knowing

  • Single httpx.AsyncClient per process. Created lazily, closed in the FastMCP lifespan teardown. Amortizes connection setup; respects keep-alive limits. The lifespan is reference-counted: under the Streamable HTTP transport the SDK enters it per request, so teardown only runs when the last holder exits.

  • Rate limit is enforced at the client, not the API. A semaphore + last-request timestamp ensures we never exceed the per-tier interval even when the MCP host issues tool calls in parallel.

  • Retry is bounded and jittered. Up to MAX_RETRIES = 3, base 1 s, capped at 30 s. Honors Retry-After when present.

  • Errors are typed. Status codes map onto a small exception hierarchy so callers can branch on AuthenticationError vs RateLimitError vs NotFoundError instead of parsing strings.

  • Input validation is pre-flight. Paper IDs are checked before any outbound request; bad IDs never hit the wire.

  • Version is single-source. __version__ is derived from importlib.metadata.version("s2-mcp-server"), so bumping pyproject.toml is sufficient; release-please bumps the manifest, server.json (×2 paths), CITATION.cff, and .zenodo.json in lockstep on every release.


Configuration

API Key Options

You can provide your API key in three ways:

  1. Environment Variable (recommended for persistent use):

    export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"
  2. Per-request HTTP header (Streamable HTTP transport only): send x-api-key: your-key with each request — see Remote access (Streamable HTTP).

  3. Per-Request Parameter (overrides env var):

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

    Deprecated: per-request api_key is deprecated and will be removed in v2.0.0. Tool-call arguments may be visible in MCP transcripts, client logs, and the LLM's tool-call history. Use the SEMANTIC_SCHOLAR_API_KEY environment variable instead. See SECURITY.md for details.

Get a free API key at: https://www.semanticscholar.org/product/api

Claude Desktop Setup

Add to your Claude Desktop config file:

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

Then restart Claude Desktop.


Remote access (Streamable HTTP)

stdio remains the default transport. --transport http serves the same 14 tools over the MCP Streamable HTTP transport, which is what remote clients — claude.ai custom connectors, Smithery listings, mcp-remote bridges — connect to.

Requires s2-mcp-server ≥ 1.5.0. Earlier releases (≤ 1.4.0) do not parse CLI flags: they silently ignore --transport http and start a stdio server instead, never opening the port.

# 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

Flags and environment variables

Flag

Env var

Default

Meaning

--transport

MCP_TRANSPORT

stdio

stdio, http (alias: streamable-http)

--host

MCP_HOST

127.0.0.1

Bind address (0.0.0.0 in the Docker image)

--port

MCP_PORT, then PORT

8000

Bind port (PORT is honored for hosting platforms)

--path

MCP_PATH

/mcp

URL path of the MCP endpoint

--allowed-host (repeatable)

MCP_ALLOWED_HOSTS (comma-separated)

localhost only

Extra Host header values admitted by the DNS-rebinding guard, e.g. mcp.example.org:* (≥ 1.7.1)

--allowed-origin (repeatable)

MCP_ALLOWED_ORIGINS (comma-separated)

localhost only

Extra Origin header values admitted by the DNS-rebinding guard, e.g. https://mcp.example.org (≥ 1.7.1)

--version

—

—

Print the package version and exit

—

MCP_STATELESS_HTTP

true

One independent server interaction per request (recommended)

—

MCP_JSON_RESPONSE

true

Plain JSON responses instead of SSE streams

CLI flags beat environment variables. The server is stateless and returns JSON by default — the configuration recommended for production Streamable HTTP deployments — and no tool relies on sessions, streaming, or server-initiated messages, so there is no functional trade-off.

Per-request API keys (bring your own key)

When served over HTTP, each request may carry its own Semantic Scholar API key; concurrent users never share or observe each other's keys. Sources, in precedence order:

  1. x-api-key HTTP header (recommended)

  2. SEMANTIC_SCHOLAR_API_KEY query parameter (Smithery session config)

  3. api_key query parameter

  4. Legacy base64 ?config= parameter (older Smithery deployments)

A request without a key falls back to the server's SEMANTIC_SCHOLAR_API_KEY environment variable, or to keyless public-tier access.

Client configuration

Claude Code

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

JSON config (clients that accept a url)

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

claude.ai custom connectors require a public HTTPS URL and accept either authless servers or OAuth — API keys in the connector URL are not supported by claude.ai. Host the server with the key supplied server-side (SEMANTIC_SCHOLAR_API_KEY env var) and register the public /mcp URL as the connector.

Smithery lists remote servers by URL (smithery mcp publish <url>); the per-request key extraction above is compatible with Smithery session config out of the box.

Security notes

  • The HTTP transport performs no authentication of inbound callers. The default bind is loopback (127.0.0.1). Expose it publicly only behind a TLS-terminating reverse proxy.

  • The built-in Uvicorn request access log is disabled to avoid recording URL credentials, but proxies, gateways and other upstream systems may still log full request URLs. Query parameters, including base64 ?config=, are not safe places for secrets. Prefer the x-api-key header or a server-side environment variable. See SECURITY.md.

  • See SECURITY.md for the project's broader threat model.


Supported ID Formats

The server accepts the following paper identifier formats:

Format

Pattern

Example

Semantic Scholar ID

40-character hex

649def34f8be52c8b66281af98ae884c09aef38b

DOI

DOI:xxx

DOI:10.1038/s41586-021-03819-2

ArXiv

ARXIV:xxx

ARXIV:2106.15928 or 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

A syntactically accepted identifier can still be absent from Semantic Scholar's index. HTTP 404 does not establish that the underlying DOI is malformed or nonexistent in other bibliographic registries.


Tools Reference

1. semantic_scholar_search_papers

Search for academic papers with advanced filters.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Plain-text search query, sent unchanged (no special syntax is documented for this endpoint; use semantic_scholar_bulk_search for boolean/phrase syntax)

year

string

No

Year filter: "2024", "2020-2024", or "2020-"

fields_of_study

string[]

No

Filter by fields: ["Computer Science", "Biology"]

publication_types

string[]

No

Filter by type: ["Review", "JournalArticle"]

open_access_only

boolean

No

Only return open access papers (default: false)

min_citation_count

integer

No

Minimum citation count

limit

integer

No

Max results 1-100 (default: 10)

offset

integer

No

Pagination offset (default: 0)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

Example:

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

JSON Example:

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

2. semantic_scholar_get_paper

Get detailed information about a specific paper.

Parameters:

Parameter

Type

Required

Description

paper_id

string

Yes

Paper ID in any supported format

include_citations

boolean

No

Include citing papers (default: false)

include_references

boolean

No

Include referenced papers (default: false)

citations_limit

integer

No

Max citing papers per page, 1-100 (default: 10)

citations_offset

integer

No

Offset for citing papers (default: 0)

references_limit

integer

No

Max referenced papers per page, 1-100 (default: 10)

references_offset

integer

No

Offset for referenced papers (default: 0)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

Example:

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

JSON Example:

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

Citation and reference pages are independent. In JSON mode, requested directions retain the existing citations / references arrays and additionally return citations_page / references_page metadata with offset and next. When next is non-null, use it as that direction's *_offset on the next call with the same paper ID and limit. A null next means no continuation was advertised by Semantic Scholar. Markdown mode prints a continuation hint when one is available. Never treat a first page as a complete citation graph.


3. semantic_scholar_search_authors

Search for academic authors by name.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Author name to search

limit

integer

No

Max results 1-100 (default: 10)

offset

integer

No

Pagination offset (default: 0)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

Example:

Find author "Yoshua Bengio"

JSON Example:

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

4. semantic_scholar_get_author

Get author profile with publications.

Parameters:

Parameter

Type

Required

Description

author_id

string

Yes

Semantic Scholar author ID

include_papers

boolean

No

Include publications (default: true)

papers_limit

integer

No

Max papers to return 1-100 (default: 20)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

Example:

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

JSON Example:

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

5. semantic_scholar_recommendations

Get AI-powered paper recommendations based on a seed paper.

Parameters:

Parameter

Type

Required

Description

paper_id

string

Yes

Seed paper ID in any supported format

from_pool

string

No

Recommendation pool: "recent" (default) or "all-cs"

limit

integer

No

Max recommendations 1-100 (default: 10)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

Example:

Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38b

JSON Example:

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

6. semantic_scholar_bulk_papers

Retrieve multiple papers in a single request (max 500).

Parameters:

Parameter

Type

Required

Description

paper_ids

string[]

Yes

List of paper IDs (max 500)

response_format

string

No

"markdown" or "json" (default: json)

api_key

string

No

Override environment API key

Example:

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

JSON Example:

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

7. semantic_scholar_bulk_search

Search papers with sorting and cursor-based pagination for large result sets. Unlike search_papers, supports a sort order and returns a token for paging through all results.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Search query; supports + (AND), | (OR), - (NOT), "phrase", * prefix, ( ) grouping

sort

string

No

Sort order, e.g. "citationCount:desc", "publicationDate:asc"

token

string

No

Continuation token from a previous bulk_search response

year

string

No

Year filter: "2024", "2020-2024", "2020-"

fields_of_study

string[]

No

Filter by fields: ["Computer Science"]

publication_types

string[]

No

Filter by type: ["Review", "JournalArticle"]

min_citation_count

integer

No

Minimum citation count

limit

integer

No

Requested page size 1-1000 (default: 100). Forwarded, but the observed API ignores it and returns up to 1000 papers per page; the full page and its token are returned unchanged

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: total result count, the page of papers, and a token for the next page (when more results exist).


8. semantic_scholar_export_citation

Return Semantic Scholar's automatically generated BibTeX entry verbatim.

Parameters:

Parameter

Type

Required

Description

paper_id

string

Yes

Paper ID in any supported format

format

string

No

Citation format (currently only "bibtex")

api_key

string

No

Override environment API key

JSON Example:

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

Returns: the BibTeX entry supplied by Semantic Scholar, without alteration. The server does not independently validate or correct bibliographic metadata; DOI, authors, title, venue, or other fields may be missing or inaccurate. Verify against authoritative records before citing in a publication.


9. semantic_scholar_match_paper

Find the single best paper matching a title string. Returns a numeric matchScore alongside the matched paper.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Paper title to match (1-500 chars)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: the best-matching paper plus its matchScore, or "No matching paper found." if no match.


10. semantic_scholar_paper_authors

Get full author profiles for a paper's authors (richer than the abbreviated author list returned by get_paper).

Parameters:

Parameter

Type

Required

Description

paper_id

string

Yes

Paper ID in any supported format

limit

integer

No

Max authors to return 1-1000 (default: 100)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: the list of full author records for the paper.


11. semantic_scholar_author_batch

Retrieve multiple authors in a single request (max 1000).

Parameters:

Parameter

Type

Required

Description

author_ids

string[]

Yes

List of author IDs (1-1000)

response_format

string

No

"markdown" or "json" (default: json)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: counts of requested / retrieved, the retrieved author records, and a not_found list of IDs the API did not return.


12. semantic_scholar_multi_recommend

Get recommendations using multiple positive (and optional negative) example papers.

Parameters:

Parameter

Type

Required

Description

positive_paper_ids

string[]

Yes

Papers to find similar results for (1-100)

negative_paper_ids

string[]

No

Papers to steer recommendations away from (0-100)

limit

integer

No

Max recommendations 1-500 (default: 10)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: the recommended papers plus an echo of the positive/negative seeds used.


13. semantic_scholar_snippet_search

Search within paper full text and return text snippets with surrounding context. Heavily rate-limited without an API key.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Search query for paper text (1-500 chars)

paper_ids

string[]

No

Limit search to specific papers (max 100)

year

string

No

Year filter: "2024", "2020-2024", "2020-"

fields_of_study

string[]

No

Filter by fields: ["Computer Science"]

min_citation_count

integer

No

Minimum citation count

limit

integer

No

Max results 1-100 (default: 10)

response_format

string

No

"markdown" or "json" (default: markdown)

api_key

string

No

Override environment API key

JSON Example:

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

Returns: matching snippets, each with the source paper title, section, and a short text excerpt.


14. semantic_scholar_status

Check server health and API connectivity status.

Parameters: None

Example:

Check Semantic Scholar API status

Response:

{
  "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
}

Rate Limits

Semantic Scholar's current API guidance says introductory API keys receive 1 request/second across all endpoints, while some keys may receive a higher rate after review. Unauthenticated requests share upstream capacity and may be throttled during heavy use.

The server therefore uses these conservative client-side defaults:

Access

Client minimum interval

Effective client maximum

No API key

1.0 seconds

1 req/sec

API key

1.1 seconds

~0.91 req/sec

If Semantic Scholar has explicitly assigned your key a different quota, set SEMANTIC_SCHOLAR_MIN_SECONDS_BETWEEN_REQUESTS to an interval that stays below that ceiling. For example, a reviewed 10 RPS quota should use an interval slightly greater than 0.1 seconds rather than assuming every API key has that rate. The setting is process-wide, so remote deployments accepting multiple user-provided keys should configure it for the slowest accepted quota.

The server automatically handles rate limiting with:

  • Request serialization to enforce minimum intervals

  • Exponential backoff retry for 429 (rate limit), 502 (bad gateway), and 503 (service unavailable) errors

  • Maximum 3 retries with jitter


Development

# 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/

Security

API keys are never persisted to disk by the server. When the server makes authenticated requests, the key is sent only to api.semanticscholar.org over HTTPS as the x-api-key header. No telemetry is sent to any third party. Under the default stdio transport the server runs locally on your machine; if you connect to a remotely hosted instance over Streamable HTTP, your per-request key also transits that endpoint's operator before being forwarded to Semantic Scholar — only send keys to remote endpoints you trust, and only over HTTPS.

Prefer the SEMANTIC_SCHOLAR_API_KEY environment variable over the per-request api_key tool parameter. The per-request parameter is deprecated (removal planned for v2.0.0) because tool-call arguments may be visible in MCP transcripts and client logs. See SECURITY.md for vulnerability reporting and the known-limitations list.


  • alphafold-sovereign-mcp — Model Context Protocol server for AlphaFold DB and other public biomedical data sources, with a local SQLite knowledge graph (pip install alphafold-sovereign-mcp).

  • uniprot-mcp — Model Context Protocol server for UniProt Swiss-Prot and TrEMBL (pip install uniprot-mcp-server).


License

MIT License - see LICENSE file.


Author

Santiago Maniches


Contributing

Contributions welcome! Please read our Contributing Guidelines.


Support


Available Tools

14 tools
semantic_scholar_author_batchA
Read-onlyIdempotent

Retrieve multiple authors in a single request (max 1000).

Inputs: params (required).

semantic_scholar_bulk_papersA
Read-onlyIdempotent

Retrieve multiple papers in a single request (max 500).

Inputs: params (required).

semantic_scholar_export_citationA
Read-onlyIdempotent

Export a citation for a paper in BibTeX format.

Use once you have a paper ID (from semantic_scholar_search_papers or
semantic_scholar_match_paper), e.g. paper_id='DOI:10.18653/v1/N18-3011'.
Returns the BibTeX entry as plain text - there is no response_format
option. Raises an error for an unknown ID, a paper without citation data,
or any format other than 'bibtex'.

Inputs: params (required).

semantic_scholar_get_authorB
Read-onlyIdempotent

Get author profile with optional publications list.

Inputs: params (required).

semantic_scholar_get_paperA
Read-onlyIdempotent

Get paper details. Accepts: S2 ID, DOI:xxx, ARXIV:xxx, PMID:xxx, CorpusId:xxx

Returns title, abstract, authors, venue, year, citation counts, TLDR,
and open-access PDF link for one paper, e.g. paper_id='ARXIV:1706.03762'.
Set include_citations / include_references to also list citing and
referenced papers (fetched in parallel, 1-100 per page each). Paginate
the two directions independently with citations_offset/references_offset;
JSON output exposes citations_page.next and references_page.next.
Results are cached
in memory for 5 minutes; an unknown ID raises a not-found error. Client-side
requests use a 1.0-second unkeyed interval and a conservative 1.1-second
authenticated default; explicitly higher S2-assigned quotas can be configured.
429/502/503 responses retry automatically with backoff. Returns
Markdown by default, response_format='json' for raw JSON. To fetch many
papers at once use semantic_scholar_bulk_papers.

Inputs: params (required).

semantic_scholar_match_paperA
Read-onlyIdempotent

Find the closest title match; preserve S2's unscaled numeric matchScore.

Inputs: params (required).

semantic_scholar_multi_recommendA
Read-onlyIdempotent

Get recommendations using multiple positive and negative example papers.

Use instead of semantic_scholar_recommendations when steering with more
than one example: results resemble positive_paper_ids and are pushed away
from negative_paper_ids. Example:
positive_paper_ids=['ARXIV:1706.03762', 'DOI:10.18653/v1/N19-1423'],
negative_paper_ids=['ARXIV:1409.0473']. Accepts 1-100 positive and up to
100 negative IDs in any supported paper-ID format; malformed IDs raise an
error before any request is made. Returns up to `limit` (1-500, default
10) papers, Markdown by default or response_format='json' for raw JSON.

Inputs: params (required).

semantic_scholar_paper_authorsA
Read-onlyIdempotent

Get full author profiles for a paper's authors.

Unlike the abbreviated author list embedded in semantic_scholar_get_paper
results, this returns each author's complete profile - affiliations,
h-index, paper and citation counts - plus author IDs usable with
semantic_scholar_get_author. Example: paper_id='DOI:10.18653/v1/N18-3011'.
Authors are returned in listed order (limit 1-1000, default 100). Returns
Markdown by default, response_format='json' for raw JSON.

Inputs: params (required).

semantic_scholar_recommendationsA
Read-onlyIdempotent

Get paper recommendations based on a seed paper.

Provide one paper you already know (e.g. paper_id='ARXIV:1706.03762') and
receive up to `limit` similar papers. from_pool picks the candidate pool:
'recent' (default, recently published papers from all fields) or 'all-cs'
(computer-science papers of any age). When steering with several positive
or negative examples, use semantic_scholar_multi_recommend instead. An
unknown seed ID raises a not-found error. Client-side requests use a
1.0-second unkeyed interval and a conservative 1.1-second authenticated
default; explicitly higher S2-assigned quotas can be configured. 429/502/503
responses retry automatically with backoff. Returns Markdown by default,
response_format='json' for raw JSON.

Inputs: params (required).

semantic_scholar_search_authorsA
Read-onlyIdempotent

Search for academic authors by name.

Example: query='Yoshua Bengio'. Several distinct researchers can share a
name, so confirm identity with semantic_scholar_get_author (affiliations,
h-index, publications) before attributing work; to list the authors of a
specific paper use semantic_scholar_paper_authors instead. Page with
offset/limit (max 100 per call, default 10). Returns Markdown by default,
response_format='json' for raw JSON.

Inputs: params (required).

semantic_scholar_search_papersA
Read-onlyIdempotent

Search for academic papers.

Relevance-ranked plain-text search over 200M+ papers, with year,
field-of-study, publication-type, open-access, and citation-count filters.
The query is sent unchanged; boolean and quoted-phrase syntax is
documented only for semantic_scholar_bulk_search. Page with
offset/limit (max 100 per call). For sorted or very large result sets
use semantic_scholar_bulk_search; to search inside paper full text use
semantic_scholar_snippet_search; to resolve one known title use
semantic_scholar_match_paper. Returns Markdown by default,
response_format='json' for raw JSON.

Inputs: params (required).

semantic_scholar_statusA
Read-onlyIdempotent

Check server health, API connectivity, and key status.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation4/5

    Search-related tools (search_papers, bulk_search, snippet_search, match_paper) overlap in broad purpose, but descriptions explicitly cross-reference and delineate use cases; author and recommendation variants are also clearly separated. Minor potential confusion remains between search_papers and bulk_search, so not perfect.

    Naming Consistency3/5

    All names use the semantic_scholar_ prefix and snake_case, but suffix conventions mix verb_noun forms (search_papers, get_author) with noun phrases (recommendations, bulk_papers, paper_authors, author_batch, status). Word order is also inconsistent between bulk_search and search_papers, though names remain readable.

    Tool Count5/5

    Fourteen tools is well within a reasonable range for a broad academic-paper API, and each tool maps to a distinct operation or useful batch variant. The set does not feel bloated; core search, retrieval, author, recommendation, and export workflows each earn their place.

    Completeness4/5

    The surface covers core read-only Semantic Scholar workflows: relevance search, bulk search, snippet search, title matching, paper detail and bulk retrieval, author search/profile/batch/paper authors, recommendations, citation export, and health status. Minor gaps include BibTeX-only citation export and no standalone citation/reference graph tool, though get_paper can include those lists.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers