Semantic Scholar MCP Server
This MCP server gives agents access to Semantic Scholar’s 200M+ paper corpus for academic research workflows through 14 typed tools.
Search papers with year, field, publication type, open-access, citation, offset/limit, and JSON/Markdown output filters.
Retrieve detailed paper metadata, abstracts, TLDRs, PDF links, and paginated citations/references.
Search author names and retrieve author profiles with publications.
Get single-seed or multi-seed recommendations, including positive/negative steering examples.
Bulk-fetch up to 500 papers or 1,000 authors in one call.
Run advanced bulk paper searches with sorting, boolean/phrase syntax, and cursor-based pagination.
Export a paper’s BibTeX citation.
Match a title string to the closest paper and return its match score.
Get full author profiles for a paper’s authors.
Search inside paper full text and return contextual snippets.
Resolve seven paper-ID formats: Semantic Scholar ID, DOI, ArXiv, PubMed, Corpus ID, ACL, and URL.
Check server health, API connectivity, key configuration, and rate-limit status.
Provides comprehensive access to 200M+ academic papers through Semantic Scholar's API, including advanced paper search with filters, full paper details with citations and references, author profiles with h-index and publications, AI-powered paper recommendations, and bulk retrieval of up to 500 papers. Supports multiple identifier formats including Semantic Scholar ID, DOI, ArXiv, PubMed, ACL, and CorpusId.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Semantic Scholar MCP Server find recent papers about large language models with over 500 citations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 CodeRuntime 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 |
|
SLSA build provenance (container image) | the |
|
PEP 740 attestations | the PyPI upload itself carries Sigstore-backed attestations under Trusted Publishing |
|
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 |
|
SHA-pinned Actions | every CI action is pinned to a commit SHA, so the release pipeline itself cannot silently change | all jobs in |
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-mcpThe 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 | manual paging over two endpoints |
Bulk operations | papers (≤500) and authors (≤1000) in one call | caller batches and paginates |
Full-text snippet search |
| separate endpoint, caller-assembled |
Paper-ID resolution | seven formats — Semantic Scholar ID, DOI, ArXiv, PubMed, Corpus ID, ACL, URL — validated pre-flight ( | caller normalizes and validates IDs |
Rate limiting | client-side limiter with a conservative S2-compatible authenticated default and configurable assigned quota ( | caller throttles by hand |
Retry / backoff | bounded, jittered retry on 429/502/503/timeout, honors | caller implements retry |
Errors | typed exception hierarchy, branchable by caller ( | parse HTTP status strings |
Output | chat-tuned Markdown or JSON per call ( | 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
Option 1: One-Line Install (Recommended)
# No cloning needed — runs directly from PyPI
uvx s2-mcp-serverOption 2: Claude Code
claude mcp add semantic-scholar -- uvx s2-mcp-serverOption 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-mcpOption 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 httpSee 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" --> S2RecsModule responsibilities (src/semantic_scholar_mcp/):
Module | Responsibility |
| FastMCP instance, 14 |
| Streamable HTTP transport: CLI/env parsing ( |
| Shared |
| Pydantic input models per tool, |
| Pre-flight paper-ID validation. Rejects NUL bytes, |
| In-memory TTL cache (5 min, 200 entries, oldest-first eviction) for paper/author lookups within a session. |
| Markdown renderers for paper and author dicts, tuned for chat-surface readability. |
|
|
| One-JSON-per-line |
Design choices worth knowing
Single
httpx.AsyncClientper 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. HonorsRetry-Afterwhen present.Errors are typed. Status codes map onto a small exception hierarchy so callers can branch on
AuthenticationErrorvsRateLimitErrorvsNotFoundErrorinstead 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 fromimportlib.metadata.version("s2-mcp-server"), so bumpingpyproject.tomlis sufficient; release-please bumps the manifest,server.json(×2 paths),CITATION.cff, and.zenodo.jsonin lockstep on every release.
Configuration
API Key Options
You can provide your API key in three ways:
Environment Variable (recommended for persistent use):
export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"Per-request HTTP header (Streamable HTTP transport only): send
x-api-key: your-keywith each request — see Remote access (Streamable HTTP).Per-Request Parameter (overrides env var):
{ "api_key": "your-api-key-here" }Deprecated: per-request
api_keyis 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 theSEMANTIC_SCHOLAR_API_KEYenvironment 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 httpand 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 httpFlags and environment variables
Flag | Env var | Default | Meaning |
|
|
|
|
|
|
| Bind address ( |
|
|
| Bind port ( |
|
|
| URL path of the MCP endpoint |
|
| localhost only | Extra |
|
| localhost only | Extra |
| — | — | Print the package version and exit |
— |
|
| One independent server interaction per request (recommended) |
— |
|
| 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:
x-api-keyHTTP header (recommended)SEMANTIC_SCHOLAR_API_KEYquery parameter (Smithery session config)api_keyquery parameterLegacy 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 thex-api-keyheader 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 |
|
DOI |
|
|
ArXiv |
|
|
PubMed |
|
|
Corpus ID |
|
|
ACL |
|
|
URL |
|
|
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 |
| string | Yes | Plain-text search query, sent unchanged (no special syntax is documented for this endpoint; use |
| string | No | Year filter: |
| string[] | No | Filter by fields: |
| string[] | No | Filter by type: |
| boolean | No | Only return open access papers (default: false) |
| integer | No | Minimum citation count |
| integer | No | Max results 1-100 (default: 10) |
| integer | No | Pagination offset (default: 0) |
| string | No |
|
| string | No | Override environment API key |
Example:
Search for "transformer attention mechanism" papers from 2023 with at least 100 citationsJSON 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 |
| string | Yes | Paper ID in any supported format |
| boolean | No | Include citing papers (default: false) |
| boolean | No | Include referenced papers (default: false) |
| integer | No | Max citing papers per page, 1-100 (default: 10) |
| integer | No | Offset for citing papers (default: 0) |
| integer | No | Max referenced papers per page, 1-100 (default: 10) |
| integer | No | Offset for referenced papers (default: 0) |
| string | No |
|
| string | No | Override environment API key |
Example:
Get details for DOI:10.1038/s41586-021-03819-2 including its top 20 citationsJSON 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 |
| string | Yes | Author name to search |
| integer | No | Max results 1-100 (default: 10) |
| integer | No | Pagination offset (default: 0) |
| string | No |
|
| 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 |
| string | Yes | Semantic Scholar author ID |
| boolean | No | Include publications (default: true) |
| integer | No | Max papers to return 1-100 (default: 20) |
| string | No |
|
| string | No | Override environment API key |
Example:
Get author profile for author ID 1741101 with their top 50 publicationsJSON 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 |
| string | Yes | Seed paper ID in any supported format |
| string | No | Recommendation pool: |
| integer | No | Max recommendations 1-100 (default: 10) |
| string | No |
|
| string | No | Override environment API key |
Example:
Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38bJSON 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 |
| string[] | Yes | List of paper IDs (max 500) |
| string | No |
|
| string | No | Override environment API key |
Example:
Retrieve these papers: DOI:10.1038/nature12373, ARXIV:2106.15928, PMID:32908142JSON 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 |
| string | Yes | Search query; supports |
| string | No | Sort order, e.g. |
| string | No | Continuation token from a previous bulk_search response |
| string | No | Year filter: |
| string[] | No | Filter by fields: |
| string[] | No | Filter by type: |
| integer | No | Minimum citation count |
| 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 |
| string | No |
|
| 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 |
| string | Yes | Paper ID in any supported format |
| string | No | Citation format (currently only |
| 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 |
| string | Yes | Paper title to match (1-500 chars) |
| string | No |
|
| 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 |
| string | Yes | Paper ID in any supported format |
| integer | No | Max authors to return 1-1000 (default: 100) |
| string | No |
|
| 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 |
| string[] | Yes | List of author IDs (1-1000) |
| string | No |
|
| 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 |
| string[] | Yes | Papers to find similar results for (1-100) |
| string[] | No | Papers to steer recommendations away from (0-100) |
| integer | No | Max recommendations 1-500 (default: 10) |
| string | No |
|
| 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 |
| string | Yes | Search query for paper text (1-500 chars) |
| string[] | No | Limit search to specific papers (max 100) |
| string | No | Year filter: |
| string[] | No | Filter by fields: |
| integer | No | Minimum citation count |
| integer | No | Max results 1-100 (default: 10) |
| string | No |
|
| 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 statusResponse:
{
"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.
Related MCP servers by the same author
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
Founder & CEO, TOPOLOGICA LLC
ORCID: 0009-0005-6480-1987
LinkedIn: santiago-maniches
Website: topologica.ai
Contributing
Contributions welcome! Please read our Contributing Guidelines.
Support
Issues: GitHub Issues
Contact: santiago@topologica.ai
Available Tools
14 toolssemantic_scholar_author_batchARead-onlyIdempotent
Retrieve multiple authors in a single request (max 1000).
Inputs: params (required).
semantic_scholar_bulk_papersARead-onlyIdempotent
Retrieve multiple papers in a single request (max 500).
Inputs: params (required).
semantic_scholar_bulk_searchARead-onlyIdempotent
Search papers with sorting and cursor-based pagination for large result sets.
Unlike regular search, supports sorting (e.g., by citation count), boolean
query syntax, and returns a continuation token for paging through all
results. The observed endpoint ignores ``limit`` and may return up to 1000
papers per page; the full page is returned so no row is skipped.
Inputs: params (required).
semantic_scholar_export_citationARead-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_authorBRead-onlyIdempotent
Get author profile with optional publications list.
Inputs: params (required).
semantic_scholar_get_paperARead-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_paperARead-onlyIdempotent
Find the closest title match; preserve S2's unscaled numeric matchScore.
Inputs: params (required).
semantic_scholar_multi_recommendARead-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_authorsARead-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_recommendationsARead-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_authorsARead-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_papersARead-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_snippet_searchARead-onlyIdempotent
Search within paper full text. Returns text snippets with context.
Note: This endpoint is heavily rate-limited without an API key.
Inputs: params (required).
semantic_scholar_statusARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Search 340M+ academic papers — citation graphs, semantic similarity, and AI literature reviews.
Academic paper search, scientific literature, citation analysis, arXiv & semantic related-work.
Research paper search with real citations and reference formatting for AI assistants
Find related scientific papers through their citation network, from OpenAlex and Semantic Scholar.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving academic paper metadata from Semantic Scholar, including paper details, citations, and author information.20MIT
- FlicenseNot gradedqualityAmaintenanceEnables searching for academic papers, authors, and citation networks through the Semantic Scholar API. Supports full-text and title search, batch lookups, citation and reference tracking, author profiles, and paper recommendations.-
- FlicenseNot gradedqualityAmaintenanceEnables users to search and retrieve academic paper data, author profiles, citation networks, and paper recommendations via the Semantic Scholar API.-
- FlicenseNot gradedqualityAmaintenanceEnables searching academic papers, retrieving paper and author details, exploring citation networks, and receiving recommendations via the Semantic Scholar API.-