convez.ai
MCP ServerBusca & PesquisaIntermediário
smaniches

Semantic Scholar MCP Server

smaniches/semantic-scholar-mcp

Acesso a 200M+ papers acadêmicos com traversal de citações via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP com 14 ferramentas para pesquisa acadêmica, oferecendo acesso direto a 200+ milhões de papers do Semantic Scholar. Permite busca, traversal de grafos de citações, perfis de autores e recomendações, integrável com Claude Desktop, Cursor e outros clientes MCP. Inclui provenance verificável via Sigstore e SLSA.

Instalação

$npx convez-ai smaniches/semantic-scholar-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
28
Forks
2
Acompanhando
1
Saúde
100%
Último commit
há 1 semana
Versão
semantic-scholar-mcp-v1.7.15
Issues abertas
3
Contribuidores
4

Casos de uso

  • Pesquisa bibliográfica sistemática e discovery de papers relacionados
  • Análise de grafos de citações e rastreamento de influência acadêmica
  • Construção de revisões de literatura assistidas por IA com contexto verificado

Veredito

Ferramenta sólida e bem-mantida para integração de dados acadêmicos em workflows de pesquisa. O foco em provenance supply-chain e certificações SLSA indica maturidade; ideal para pesquisadores que já usam Claude ou ferramentas MCP e precisam de acesso confiável a literatura científica.

README

A tradução para o português deste README ainda está na fila.

Semantic Scholar MCP Server

CI codecov PyPI version DOI Provenance: SLSA + SBOM Docker GitHub Release License: MIT MCP Python 3.10+

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


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:

GuaranteeWhat it provesWhere 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-uploadedpublish.yml — actions/attest-build-provenance (lines 56–59)
SLSA build provenance (container image)the ghcr.io image digest was built by this repo's docker.ymldocker.yml — actions/attest-build-provenance, push-to-registry (lines 110–116)
PEP 740 attestationsthe PyPI upload itself carries Sigstore-backed attestations under Trusted Publishingpublish.yml — attestations: true (line 97)
CycloneDX SBOMa machine-readable bill of materials, generated then attested against the distributionspublish.yml — cyclonedx-py + actions/attest-sbom (lines 46–64)
SHA-pinned Actionsevery CI action is pinned to a commit SHA, so the release pipeline itself cannot silently changeall 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 serverRaw S2 REST API from an agent
Tool surface14 typed MCP tools (search, retrieval, recommendations, status)caller composes raw HTTP requests
Citation graphboth directions (citations and references) in get_papermanual paging over two endpoints
Bulk operationspapers (≤500) and authors (≤1000) in one callcaller batches and paginates
Full-text snippet searchsnippet_search with surrounding contextseparate endpoint, caller-assembled
Paper-ID resolutionseven formats — Semantic Scholar ID, DOI, ArXiv, PubMed, Corpus ID, ACL, URL — validated pre-flight (validators.py)caller normalizes and validates IDs
Rate limitingclient-side per-tier limiter, never exceeds the interval (client.py)caller throttles by hand
Retry / backoffbounded, jittered retry on 429/503/timeout, honors Retry-After (client.py)caller implements retry
Errorstyped exception hierarchy, branchable by caller (errors.py)parse HTTP status strings
Outputchat-tuned Markdown or JSON per call (formatters.py)raw JSON
Supply-chain provenanceSLSA + PEP 740 + CycloneDX SBOM per release (see above)n/a
Citabilityminted Zenodo DOI, MIT licensedn/a

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

Note: Get a free API key at semanticscholar.org/product/api. Without a key, you get rate-limited public access (1 req/sec).


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 transport, 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 (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/):

ModuleResponsibility
server.pyFastMCP instance, 14 @mcp.tool registrations, lifespan, main() entry. Re-exports the helper surface for back-compat.
client.pyShared httpx.AsyncClient singleton, per-tier rate limiter (1 req/s public, 10 req/s keyed), retry loop with exponential backoff + jitter on 429/503/timeout, HTTP→typed-exception mapping.
models.pyPydantic input models per tool, ResponseFormat enum, the four tiered field-set constants (PAPER_SEARCH_FIELDS, …_LITE, PAPER_BULK_SEARCH_FIELDS, PAPER_DETAIL_FIELDS, AUTHOR_FIELDS).
validators.pyPre-flight paper-ID validation. Rejects NUL bytes, ?, #, path traversal; accepts the seven canonical ID formats.
cache.pyIn-memory TTL cache (5 min, 200 entries, oldest-first eviction) for paper/author lookups within a session.
formatters.pyMarkdown renderers for paper and author dicts, tuned for chat-surface readability.
errors.pySemanticScholarError hierarchy: AuthenticationError, RateLimitError, NotFoundError, ValidationError, ServerError.
logging_config.pyOne-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.
  • 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 two ways:

  1. Environment Variable (recommended for persistent use):

    export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"
    
  2. 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.


Supported ID Formats

The server accepts the following paper identifier formats:

FormatPatternExample
Semantic Scholar ID40-character hex649def34f8be52c8b66281af98ae884c09aef38b
DOIDOI:xxxDOI:10.1038/s41586-021-03819-2
ArXivARXIV:xxxARXIV:2106.15928 or ARXIV:2106.15928v2
PubMedPMID:xxxPMID:32908142
Corpus IDCorpusId:xxxCorpusId:215416146
ACLACL:xxxACL:P19-1285
URLURL:xxxURL:https://arxiv.org/abs/2106.15928

Tools Reference

1. semantic_scholar_search_papers

Search for academic papers with advanced filters.

Parameters:

ParameterTypeRequiredDescription
querystringYesSearch query (supports AND, OR, NOT operators and "phrase search")
yearstringNoYear filter: "2024", "2020-2024", or "2020-"
fields_of_studystring[]NoFilter by fields: ["Computer Science", "Biology"]
publication_typesstring[]NoFilter by type: ["Review", "JournalArticle"]
open_access_onlybooleanNoOnly return open access papers (default: false)
min_citation_countintegerNoMinimum citation count
limitintegerNoMax results 1-100 (default: 10)
offsetintegerNoPagination offset (default: 0)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
paper_idstringYesPaper ID in any supported format
include_citationsbooleanNoInclude citing papers (default: false)
include_referencesbooleanNoInclude referenced papers (default: false)
citations_limitintegerNoMax citations to return 1-100 (default: 10)
references_limitintegerNoMax references to return 1-100 (default: 10)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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
}

3. semantic_scholar_search_authors

Search for academic authors by name.

Parameters:

ParameterTypeRequiredDescription
querystringYesAuthor name to search
limitintegerNoMax results 1-100 (default: 10)
offsetintegerNoPagination offset (default: 0)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
author_idstringYesSemantic Scholar author ID
include_papersbooleanNoInclude publications (default: true)
papers_limitintegerNoMax papers to return 1-100 (default: 20)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
paper_idstringYesSeed paper ID in any supported format
from_poolstringNoRecommendation pool: "recent" (default) or "all-cs"
limitintegerNoMax recommendations 1-100 (default: 10)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
paper_idsstring[]YesList of paper IDs (max 500)
response_formatstringNo"markdown" or "json" (default: json)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
querystringYesSearch query
sortstringNoSort order, e.g. "citationCount:desc", "publicationDate:asc"
tokenstringNoContinuation token from a previous bulk_search response
yearstringNoYear filter: "2024", "2020-2024", "2020-"
fields_of_studystring[]NoFilter by fields: ["Computer Science"]
publication_typesstring[]NoFilter by type: ["Review", "JournalArticle"]
min_citation_countintegerNoMinimum citation count
limitintegerNoMax results per page 1-1000 (default: 100)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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

Export a citation for a paper in BibTeX format.

Parameters:

ParameterTypeRequiredDescription
paper_idstringYesPaper ID in any supported format
formatstringNoCitation format (currently only "bibtex")
api_keystringNoOverride environment API key

JSON Example:

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

Returns: the BibTeX string for the requested paper.


9. semantic_scholar_match_paper

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

Parameters:

ParameterTypeRequiredDescription
querystringYesPaper title to match (1-500 chars)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
paper_idstringYesPaper ID in any supported format
limitintegerNoMax authors to return 1-1000 (default: 100)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
author_idsstring[]YesList of author IDs (1-1000)
response_formatstringNo"markdown" or "json" (default: json)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
positive_paper_idsstring[]YesPapers to find similar results for (1-100)
negative_paper_idsstring[]NoPapers to dissimilate from (0-100)
limitintegerNoMax recommendations 1-500 (default: 10)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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:

ParameterTypeRequiredDescription
querystringYesSearch query for paper text (1-500 chars)
paper_idsstring[]NoLimit search to specific papers (max 100)
yearstringNoYear filter: "2024", "2020-2024", "2020-"
fields_of_studystring[]NoFilter by fields: ["Computer Science"]
min_citation_countintegerNoMinimum citation count
limitintegerNoMax results 1-100 (default: 10)
response_formatstringNo"markdown" or "json" (default: markdown)
api_keystringNoOverride 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 (10 req/sec)",
  "timestamp": "2026-04-06T12:00:00.000000+00:00",
  "api_reachable": true,
  "rate_limited": false,
  "retry_after": null
}

Rate Limits

TierRequests/SecondHow to Get
No API Key1 req/secDefault
API Key10 req/secSign up (free)
Academic Partner10-100 req/secApply via S2

Note: The client-side rate limiter enforces the intervals above. The upstream Semantic Scholar API may impose stricter limits during high-traffic periods.

The server automatically handles rate limiting with:

  • Request serialization to enforce minimum intervals
  • Exponential backoff retry for 429 (rate limit) 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. The MCP server runs locally on your machine; when it 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.

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 13 other biomedical data sources, with a local SQLite knowledge graph (pip install --pre 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


Ver o original no GitHub

Bom para

Relacionados