Semantic Scholar MCP Server
Semantic Scholar MCP Server
A comprehensive 14-tool MCP server for Semantic Scholar academic research workflows. Direct access to 200M+ papers from Semantic Scholar within Claude Desktop.
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 .Note: Get a free API key at semanticscholar.org/product/api. Without a key, you get rate-limited public access (1 req/sec).
Related MCP server: Semantic Scholar MCP Server
Configuration
API Key Options
You can provide your API key in two ways:
Environment Variable (recommended for persistent use):
export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"Per-Request Parameter (overrides env var):
{ "api_key": "your-api-key-here" }Caution: per-request
api_keyvalues are part of the tool-call arguments and may be visible in MCP transcripts, client logs, and the LLM's tool-call history depending on the client. For production use, prefer theSEMANTIC_SCHOLAR_API_KEYenvironment variable. Removal of the per-request parameter is tracked for v1.3.0.
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:
Format | Pattern | Example |
Semantic Scholar ID | 40-character hex |
|
DOI |
|
|
ArXiv |
|
|
PubMed |
|
|
Corpus ID |
|
|
ACL |
|
|
URL |
|
|
Tools Reference
1. semantic_scholar_search_papers
Search for academic papers with advanced filters.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | Search query (supports AND, OR, NOT operators and "phrase search") |
| 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 citations to return 1-100 (default: 10) |
| integer | No | Max references to return 1-100 (default: 10) |
| 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
}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 |
| 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 |
| 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 | Max results per page 1-1000 (default: 100) |
| 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
Export a citation for a paper in BibTeX format.
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 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:
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 dissimilate 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": "1.2.2",
"api_key_configured": true,
"timestamp": "2026-04-06T12:00:00.000000+00:00",
"api_reachable": true
}Rate Limits
Tier | Requests/Second | How to Get |
No API Key | 1 req/sec | Default |
Free API Key | 1 req/sec | |
Academic Partner | 10-100 req/sec | Apply via S2 |
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
Architecture
+-----------------+ +----------------------+ +-----------------+
| Claude Desktop |---->| semantic-scholar-mcp |---->| Semantic Scholar|
| (MCP Client) |<----| (This Server) |<----+ API |
+-----------------+ +----------------------+ +-----------------+
| | |
| stdio (JSON-RPC) | Your API Key | HTTPS
| Local process | Local machine | 200M+ papersWhere your API key goes. The MCP server runs locally on your machine and
does not store your API key on disk. When the server makes authenticated
requests, the key is sent only to api.semanticscholar.org over HTTPS as
the x-api-key header that the Semantic Scholar API requires. No telemetry
is sent to any third party. See the per-request api_key caution above for
how transcript exposure can occur when the parameter is used per-request
instead of via the environment variable.
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. Prefer the
SEMANTIC_SCHOLAR_API_KEY environment variable over the per-request api_key
tool parameter (see SECURITY.md for details on the
transcript-exposure risk). All API communication uses HTTPS to
api.semanticscholar.org. See SECURITY.md for
vulnerability reporting and the v1.2.x known-limitations list.
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
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.-