semantic-scholar-fastmcp-mcp-server
A FastMCP server implementation for the Semantic Scholar API, providing comprehensive access to academic paper data, author information, and citation networks.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zongmin-yu--semantic-scholar-fastmcp-mcp-server)HTML
<a href="/listings/zongmin-yu--semantic-scholar-fastmcp-mcp-server"><img src="/api/listings/zongmin-yu--semantic-scholar-fastmcp-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Quick Install (PyPI)
pip install semantic-scholar-fastmcp
Or run directly with [`uvx`](https://docs.astral.sh/uv/):
uvx semantic-scholar-fastmcp
MCP Client Configuration
For any MCP client that supports `uvx`:
{
"mcpServers": {
"semantic-scholar": {
"command": "uvx",
"args": ["semantic-scholar-fastmcp"],
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
}
}
}
}Installing via Smithery
To install Semantic Scholar MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/semantic-scholar-fastmcp-mcp-server):
npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude
Manual Installation
1. Clone the repository:
git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git cd semantic-scholar-fastmcp-mcp-server
2. Install in development mode:
pip install -e ".[dev]"
3. Run the server:
semantic-scholar-mcp-server
API Key (Optional)
To get higher rate limits and better performance:
1. Get an API key from [Semantic Scholar API](https://www.semanticscholar.org/product/api) 2. Add it to your FastMCP configuration as shown above in the `env` section
If no API key is provided, the server will use unauthenticated access with lower rate limits.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 371 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- [](https://mseep.ai/app/zongmin-yu-semantic-scholar-fastmcp-mcp-server)
- # Semantic Scholar MCP Server
- [](https://smithery.ai/server/semantic-scholar-fastmcp-mcp-server)
- A FastMCP server implementation for the Semantic Scholar API, providing comprehensive access to academic paper data, author information, and citation networks.
- > **Looking for Claude Code skills?** Check out [semantic-scholar-skills](https://github.com/zongmin-yu/semantic-scholar-skills) — the next-generation toolkit that bundles this MCP server with ready-to-use Claude Code skills (`/expand-references`, `/trace-citations`, `/paper-triage`) and a Python workflow engine.
- ## Project Structure
- The project has been refactored into a modular structure for better maintainability:
- ```
- semantic-scholar-server/
- ├── semantic_scholar/ # Main package
- │ ├── __init__.py # Package initialization
- │ ├── server.py # Server setup and main functionality
- │ ├── mcp.py # Centralized FastMCP instance definition
- │ ├── config.py # Configuration classes
- │ ├── utils/ # Utility modules
- │ │ ├── __init__.py
- │ │ ├── errors.py # Error handling
- │ │ └── http.py # HTTP client and rate limiting
- │ ├── api/ # API endpoints
- │ ├── __init__.py
- │ ├── papers.py # Paper-related endpoints
- │ ├── authors.py # Author-related endpoints
- │ └── recommendations.py # Recommendation endpoints
- ├── run.py # Entry point script
- ```
- This structure:
- - Separates concerns into logical modules
- - Makes the codebase easier to understand and maintain
- - Allows for better testing and future extensions
- - Keeps related functionality grouped together
- - Centralizes the FastMCP instance to avoid circular imports
- ## Features
- - **Paper Search & Discovery**
- - Full-text search with advanced filtering
- - Title-based paper matching
- - Paper recommendations (single and multi-paper)
- - Batch paper details retrieval
- - Advanced search with ranking strategies
- - **Citation Analysis**
- - Citation network exploration
- - Reference tracking
- - Citation context and influence analysis
- - **Author Information**
- - Author search and profile details
- - Publication history
- - Batch author details retrieval
- - **Advanced Features**
- - Complex search with multiple ranking strategies
- - Customizable field selection
- - Efficient batch operations
- - Rate limiting compliance
- - Support for both authenticated and unauthenticated access
- - Graceful shutdown and error handling
- - Connection pooling and resource management
- ## System Requirements
- - Python 3.10+
- - Environment variable for API key (optional)
- ## Installation
- ### Quick Install (PyPI)
- ```bash
- pip install semantic-scholar-fastmcp
- ```
- Or run directly with [`uvx`](https://docs.astral.sh/uv/):
- ```bash
- uvx semantic-scholar-fastmcp
- ```
- ### MCP Client Configuration
- For any MCP client that supports `uvx`:
- ```json
- {
- "mcpServers": {
- "semantic-scholar": {
- "command": "uvx",
- "args": ["semantic-scholar-fastmcp"],
- "env": {
- "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
- }
- }
- }
- }
- ```
- ### Installing via Smithery
- To install Semantic Scholar MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/semantic-scholar-fastmcp-mcp-server):
- ```bash
- npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude
- ```
- ### Manual Installation
- 1. Clone the repository:
- ```bash
- git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git
- cd semantic-scholar-fastmcp-mcp-server
- ```
- 2. Install in development mode:
- ```bash
- pip install -e ".[dev]"
- ```
- 3. Run the server:
- ```bash
- semantic-scholar-mcp-server
- ```
- ### API Key (Optional)
- To get higher rate limits and better performance:
- 1. Get an API key from [Semantic Scholar API](https://www.semanticscholar.org/product/api)
- 2. Add it to your FastMCP configuration as shown above in the `env` section
- If no API key is provided, the server will use unauthenticated access with lower rate limits.
- ## Configuration
- ## Contributing
- See `CONTRIBUTING.md`.
- ### Environment Variables
- - `SEMANTIC_SCHOLAR_API_KEY`: Your Semantic Scholar API key (optional)
- - Get your key from [Semantic Scholar API](https://www.semanticscholar.org/product/api)
- - If not provided, the server will use unauthenticated access
- ### HTTP Bridge (Built-in)
- This repository includes a small HTTP bridge (`semantic_scholar.bridge`) that
- exposes a minimal REST API for common workflows.
- Default listening port: `8000`.
- Bridge configuration via environment variables:
- - `SEMANTIC_SCHOLAR_ENABLE_HTTP_BRIDGE` (default: `1`) — set to `0` to disable
- - `SEMANTIC_SCHOLAR_HTTP_BRIDGE_HOST` (default: `0.0.0.0`)
- - `SEMANTIC_SCHOLAR_HTTP_BRIDGE_PORT` (default: `8000`)
- Available endpoints:
- - `GET /v1/paper/search?q=...` — paper search (params: `fields`, `offset`, `limit`)
- - `GET /v1/paper/{paper_id}` — paper details (param: `fields`)
- - `POST /v1/paper/batch` — batch paper details (JSON: `{ "ids": [ ... ] }`)
- - `GET /v1/author/search?q=...` — author search (params: `fields`, `offset`, `limit`)
- - `GET /v1/author/{author_id}` — author details (param: `fields`)
- - `POST /v1/author/batch` — batch author details (JSON: `{ "ids": [ ... ] }`)
- - `GET /v1/recommendations?paper_id=...` — recommendations for a paper
- The bridge reuses the package's HTTP utilities (`semantic_scholar.utils.http`)
- so rate limits, API key handling and connection pooling remain consistent with
- the MCP tools.
- Example:
- ```bash
- curl 'http://localhost:8000/v1/paper/search?q=machine+learning&limit=5'
- ```
- ### Rate Limits
- The server automatically adjusts to the appropriate rate limits:
- **With API Key**:
- - Search, batch and recommendation endpoints: 1 request per second
- - Other endpoints: 10 requests per second
- **Without API Key**:
- - All endpoints: 100 requests per 5 minutes
- - Longer timeouts for requests
- > Note: Rate limits are subject to change. See [Semantic Scholar API](https://api.semanticscholar.org/) for the latest information.
- ## Semantic Scholar API Terms
- This project uses the [Semantic Scholar Academic Graph API](https://api.semanticscholar.org/), provided by the Allen Institute for AI (AI2).
- Please review the [API License Agreement](https://api.semanticscholar.org/license/) before use.
- ## Available MCP Tools
- The server currently exposes 16 MCP tools.
- > Note: All tools are aligned with the official [Semantic Scholar API documentation](https://api.semanticscholar.org/api-docs/). Please refer to the official documentation for detailed field specifications and the latest updates.
- ### Paper Search Tools
- - `paper_relevance_search`: Search for papers using relevance ranking
- - Supports comprehensive query parameters including year range and citation count filters
- - Returns paginated results with customizable fields
- - `paper_bulk_search`: Bulk paper search with sorting options
- - Similar to relevance search but optimized for larger result sets
- - Supports sorting by citation count, publication date, etc.
- - `paper_title_search`: Find papers by exact title match
- - Useful for finding specific papers when you know the title
- - Returns detailed paper information with customizable fields
- - `paper_details`: Get comprehensive details about a specific paper
- - Accepts various paper ID formats (S2 ID, DOI, ArXiv, etc.)
- - Returns detailed paper metadata with nested field support
- - `paper_batch_details`: Efficiently retrieve details for multiple papers
- - Accepts up to 1000 paper IDs per request
- - Supports the same ID formats and fields as single paper details
- - `paper_authors`: Get the authors associated with a specific paper
- - Returns paginated author results for the paper
- - Supports author field customization with offset and limit controls
- - `paper_autocomplete`: Get paper title suggestions for a partial query
- - Returns minimal paper metadata for interactive search completion
- - Truncates overly long queries to the API-supported length
- - `snippet_search`: Search within paper snippets and excerpts
- - Returns relevant text matches from titles, abstracts, and body text
- - Supports filters for paper IDs, authors, venue, year, and field of study
- ### Citation Tools
- - `paper_citations`: Get papers that cite a specific paper
- - Returns paginated list of citing papers
- - Includes citation context when available
- - Supports field customization and sorting
- - `paper_references`: Get papers referenced by a specific paper
- - Returns paginated list of referenced papers
- - Includes reference context when available
- - Supports field customization and sorting
- ### Author Tools
- - `author_search`: Search for authors by name
- - Returns paginated results with customizable fields
- - Includes affiliations and publication counts
- - `author_details`: Get detailed information about an author
- - Returns comprehensive author metadata
- - Includes metrics like h-index and citation counts
- - `author_papers`: Get papers written by an author
- - Returns paginated list of author's publications
- - Supports field customization and sorting
- - `author_batch_details`: Get details for multiple authors
- - Efficiently retrieve information for up to 1000 authors
- - Returns the same fields as single author details
- ### Recommendation Tools
- - `get_paper_recommendations_single`: Get recommendations based on a single paper
- - Returns similar papers based on content and citation patterns
- - Supports field customization for recommended papers
- - `get_paper_recommendations_multi`: Get recommendations based on multiple papers
- - Accepts positive and negative example papers
- - Returns papers similar to positive examples and dissimilar to negative ones
- ## Usage Examples
- ### Basic Paper Search
- ```python
- results = await paper_relevance_search(
- context,
- query="machine learning",
- year="2020-2024",
- min_citation_count=50,
- fields=["title", "abstract", "authors"]
- )
- ```
- ### Paper Recommendations
- ```python
- # Single paper recommendation
- recommendations = await get_paper_recommendations_single(
- context,
- paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
- fields="title,authors,year"
- )
- # Multi-paper recommendation
- recommendations = await get_paper_recommendations_multi(
- context,
- positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
- negative_paper_ids=["ArXiv:1805.02262"],
- fields="title,abstract,authors"
- )
- ```
- ### Batch Operations
- ```python
- # Get details for multiple papers
- papers = await paper_batch_details(
- context,
- paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
- fields="title,authors,year,citations"
- )
- # Get details for multiple authors
- authors = await author_batch_details(
- context,
- author_ids=["1741101", "1780531"],
- fields="name,hIndex,citationCount,paperCount"
- )
- ```
- ## Error Handling
- The server provides standardized error responses:
- ```python
- {
- "error": {
- "type": "error_type", # rate_limit, api_error, validation, timeout
- "message": "Error description",
- "details": {
- # Additional context
- "authenticated": true/false # Indicates if request was authenticated
- }
- }
- }
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.