s2-mcp-server 1.2.1

MCP server for Semantic Scholar — 200M+ academic papers in Claude Desktop

Semantic Scholar MCP Server

The most comprehensive MCP server for academic research. 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-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 .

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

---

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

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	649def34f8be52c8b66281af98ae884c09aef38b
DOI	DOI:xxx	DOI:10.1038/s41586-021-03819-2
ArXiv	ARXIV:xxx	ARXIV:2106.15928 or ARXIV:2106.15928v2
PubMed	PMID:xxx	PMID:32908142
Corpus ID	CorpusId:xxx	CorpusId:215416146
ACL	ACL:xxx	ACL:P19-1285
URL	URL:xxx	URL:https://arxiv.org/abs/2106.15928

---

Tools Reference

1. semantic_scholar_search_papers

Search for academic papers with advanced filters.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query (supports AND, OR, NOT operators and "phrase search")
year	string	No	Year filter: "2024", "2020-2024", or "2020-"
fields_of_study	string[]	No	Filter by fields: ["Computer Science", "Biology"]
publication_types	string[]	No	Filter by type: ["Review", "JournalArticle"]
open_access_only	boolean	No	Only return open access papers (default: false)
min_citation_count	integer	No	Minimum citation count
limit	integer	No	Max results 1-100 (default: 10)
offset	integer	No	Pagination offset (default: 0)
response_format	string	No	"markdown" or "json" (default: markdown)
api_key	string	No	Override environment API key

Example:

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

JSON Example:

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

---

2. semantic_scholar_get_paper

Get detailed information about a specific paper.

Parameters:

Parameter	Type	Required	Description
paper_id	string	Yes	Paper ID in any supported format
include_citations	boolean	No	Include citing papers (default: false)
include_references	boolean	No	Include referenced papers (default: false)
citations_limit	integer	No	Max citations to return 1-100 (default: 10)
references_limit	integer	No	Max references to return 1-100 (default: 10)
response_format	string	No	"markdown" or "json" (default: markdown)
api_key	string	No	Override environment API key

Example:

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

JSON Example:

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

---

3. semantic_scholar_search_authors

Search for academic authors by name.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Author name to search
limit	integer	No	Max results 1-100 (default: 10)
offset	integer	No	Pagination offset (default: 0)
response_format	string	No	"markdown" or "json" (default: markdown)
api_key	string	No	Override environment API key

Example:

Find author "Yoshua Bengio"

JSON Example:

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

---

4. semantic_scholar_get_author

Get author profile with publications.

Parameters:

Parameter	Type	Required	Description
author_id	string	Yes	Semantic Scholar author ID
include_papers	boolean	No	Include publications (default: true)
papers_limit	integer	No	Max papers to return 1-100 (default: 20)
response_format	string	No	"markdown" or "json" (default: markdown)
api_key	string	No	Override environment API key

Example:

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

JSON Example:

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

---

5. semantic_scholar_recommendations

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

Parameters:

Parameter	Type	Required	Description
paper_id	string	Yes	Seed paper ID in any supported format
limit	integer	No	Max recommendations 1-100 (default: 10)
response_format	string	No	"markdown" or "json" (default: markdown)
api_key	string	No	Override environment API key

Example:

Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38b

JSON Example:

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

---

6. semantic_scholar_bulk_papers

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

Parameters:

Parameter	Type	Required	Description
paper_ids	string[]	Yes	List of paper IDs (max 500)
response_format	string	No	"markdown" or "json" (default: json)
api_key	string	No	Override environment API key

Example:

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

JSON Example:

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

---

7. semantic_scholar_status

Check server health and API connectivity status.

Parameters: None

Example:

Check Semantic Scholar API status

Response:

{
  "server": "semantic-scholar-mcp",
  "version": "1.0.0",
  "api_key_configured": true,
  "timestamp": "2025-01-15T12: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	Sign up
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+ papers

Your API key never leaves your machine. The MCP server runs locally.

---

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 stored in code — environment variables only. See SECURITY.md for vulnerability reporting. All API communication uses HTTPS.

---

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: [e-mail]

---

Built by TOPOLOGICA LLC
Advancing computational research through topological intelligence