Semantic Scholar MCP Server

Semantic Scholar MCP Server

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

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

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

---

Provenance & supply chain

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

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

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

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

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

---

How it compares

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

---

Installation

Option 1: One-Line Install (Recommended)

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

Option 2: Claude Code

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

Option 3: Claude Desktop (Windows)

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

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

Option 4: Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Option 5: pip / From Source

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

Option 6: Docker

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

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/):

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:

---

Tools Reference

1. semantic_scholar_search_papers

Search for academic papers with advanced filters.

Parameters:

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:

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:

Example:

Find author "Yoshua Bengio"

JSON Example:

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

---

4. semantic_scholar_get_author

Get author profile with publications.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

• 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
• Discussions: GitHub Discussions
• Contact: santiago@topologica.ai

---