Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zongmin-yu--semantic-scholar-fastmcp-mcp-server/badge.svg)](/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

i

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)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/zongmin-yu-semantic-scholar-fastmcp-mcp-server-badge.png)](https://mseep.ai/app/zongmin-yu-semantic-scholar-fastmcp-mcp-server)
  2. # Semantic Scholar MCP Server
  3. [![smithery badge](https://smithery.ai/badge/semantic-scholar-fastmcp-mcp-server)](https://smithery.ai/server/semantic-scholar-fastmcp-mcp-server)
  4. A FastMCP server implementation for the Semantic Scholar API, providing comprehensive access to academic paper data, author information, and citation networks.
  5. > **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.
  6. ## Project Structure
  7. The project has been refactored into a modular structure for better maintainability:
  8. ```
  9. semantic-scholar-server/
  10. ├── semantic_scholar/ # Main package
  11. │ ├── __init__.py # Package initialization
  12. │ ├── server.py # Server setup and main functionality
  13. │ ├── mcp.py # Centralized FastMCP instance definition
  14. │ ├── config.py # Configuration classes
  15. │ ├── utils/ # Utility modules
  16. │ │ ├── __init__.py
  17. │ │ ├── errors.py # Error handling
  18. │ │ └── http.py # HTTP client and rate limiting
  19. │ ├── api/ # API endpoints
  20. │ ├── __init__.py
  21. │ ├── papers.py # Paper-related endpoints
  22. │ ├── authors.py # Author-related endpoints
  23. │ └── recommendations.py # Recommendation endpoints
  24. ├── run.py # Entry point script
  25. ```
  26. This structure:
  27. - Separates concerns into logical modules
  28. - Makes the codebase easier to understand and maintain
  29. - Allows for better testing and future extensions
  30. - Keeps related functionality grouped together
  31. - Centralizes the FastMCP instance to avoid circular imports
  32. ## Features
  33. - **Paper Search & Discovery**
  34. - Full-text search with advanced filtering
  35. - Title-based paper matching
  36. - Paper recommendations (single and multi-paper)
  37. - Batch paper details retrieval
  38. - Advanced search with ranking strategies
  39. - **Citation Analysis**
  40. - Citation network exploration
  41. - Reference tracking
  42. - Citation context and influence analysis
  43. - **Author Information**
  44. - Author search and profile details
  45. - Publication history
  46. - Batch author details retrieval
  47. - **Advanced Features**
  48. - Complex search with multiple ranking strategies
  49. - Customizable field selection
  50. - Efficient batch operations
  51. - Rate limiting compliance
  52. - Support for both authenticated and unauthenticated access
  53. - Graceful shutdown and error handling
  54. - Connection pooling and resource management
  55. ## System Requirements
  56. - Python 3.10+
  57. - Environment variable for API key (optional)
  58. ## Installation
  59. ### Quick Install (PyPI)
  60. ```bash
  61. pip install semantic-scholar-fastmcp
  62. ```
  63. Or run directly with [`uvx`](https://docs.astral.sh/uv/):
  64. ```bash
  65. uvx semantic-scholar-fastmcp
  66. ```
  67. ### MCP Client Configuration
  68. For any MCP client that supports `uvx`:
  69. ```json
  70. {
  71. "mcpServers": {
  72. "semantic-scholar": {
  73. "command": "uvx",
  74. "args": ["semantic-scholar-fastmcp"],
  75. "env": {
  76. "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
  77. }
  78. }
  79. }
  80. }
  81. ```
  82. ### Installing via Smithery
  83. To install Semantic Scholar MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/semantic-scholar-fastmcp-mcp-server):
  84. ```bash
  85. npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude
  86. ```
  87. ### Manual Installation
  88. 1. Clone the repository:
  89. ```bash
  90. git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git
  91. cd semantic-scholar-fastmcp-mcp-server
  92. ```
  93. 2. Install in development mode:
  94. ```bash
  95. pip install -e ".[dev]"
  96. ```
  97. 3. Run the server:
  98. ```bash
  99. semantic-scholar-mcp-server
  100. ```
  101. ### API Key (Optional)
  102. To get higher rate limits and better performance:
  103. 1. Get an API key from [Semantic Scholar API](https://www.semanticscholar.org/product/api)
  104. 2. Add it to your FastMCP configuration as shown above in the `env` section
  105. If no API key is provided, the server will use unauthenticated access with lower rate limits.
  106. ## Configuration
  107. ## Contributing
  108. See `CONTRIBUTING.md`.
  109. ### Environment Variables
  110. - `SEMANTIC_SCHOLAR_API_KEY`: Your Semantic Scholar API key (optional)
  111. - Get your key from [Semantic Scholar API](https://www.semanticscholar.org/product/api)
  112. - If not provided, the server will use unauthenticated access
  113. ### HTTP Bridge (Built-in)
  114. This repository includes a small HTTP bridge (`semantic_scholar.bridge`) that
  115. exposes a minimal REST API for common workflows.
  116. Default listening port: `8000`.
  117. Bridge configuration via environment variables:
  118. - `SEMANTIC_SCHOLAR_ENABLE_HTTP_BRIDGE` (default: `1`) — set to `0` to disable
  119. - `SEMANTIC_SCHOLAR_HTTP_BRIDGE_HOST` (default: `0.0.0.0`)
  120. - `SEMANTIC_SCHOLAR_HTTP_BRIDGE_PORT` (default: `8000`)
  121. Available endpoints:
  122. - `GET /v1/paper/search?q=...` — paper search (params: `fields`, `offset`, `limit`)
  123. - `GET /v1/paper/{paper_id}` — paper details (param: `fields`)
  124. - `POST /v1/paper/batch` — batch paper details (JSON: `{ "ids": [ ... ] }`)
  125. - `GET /v1/author/search?q=...` — author search (params: `fields`, `offset`, `limit`)
  126. - `GET /v1/author/{author_id}` — author details (param: `fields`)
  127. - `POST /v1/author/batch` — batch author details (JSON: `{ "ids": [ ... ] }`)
  128. - `GET /v1/recommendations?paper_id=...` — recommendations for a paper
  129. The bridge reuses the package's HTTP utilities (`semantic_scholar.utils.http`)
  130. so rate limits, API key handling and connection pooling remain consistent with
  131. the MCP tools.
  132. Example:
  133. ```bash
  134. curl 'http://localhost:8000/v1/paper/search?q=machine+learning&limit=5'
  135. ```
  136. ### Rate Limits
  137. The server automatically adjusts to the appropriate rate limits:
  138. **With API Key**:
  139. - Search, batch and recommendation endpoints: 1 request per second
  140. - Other endpoints: 10 requests per second
  141. **Without API Key**:
  142. - All endpoints: 100 requests per 5 minutes
  143. - Longer timeouts for requests
  144. > Note: Rate limits are subject to change. See [Semantic Scholar API](https://api.semanticscholar.org/) for the latest information.
  145. ## Semantic Scholar API Terms
  146. This project uses the [Semantic Scholar Academic Graph API](https://api.semanticscholar.org/), provided by the Allen Institute for AI (AI2).
  147. Please review the [API License Agreement](https://api.semanticscholar.org/license/) before use.
  148. ## Available MCP Tools
  149. The server currently exposes 16 MCP tools.
  150. > 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.
  151. ### Paper Search Tools
  152. - `paper_relevance_search`: Search for papers using relevance ranking
  153. - Supports comprehensive query parameters including year range and citation count filters
  154. - Returns paginated results with customizable fields
  155. - `paper_bulk_search`: Bulk paper search with sorting options
  156. - Similar to relevance search but optimized for larger result sets
  157. - Supports sorting by citation count, publication date, etc.
  158. - `paper_title_search`: Find papers by exact title match
  159. - Useful for finding specific papers when you know the title
  160. - Returns detailed paper information with customizable fields
  161. - `paper_details`: Get comprehensive details about a specific paper
  162. - Accepts various paper ID formats (S2 ID, DOI, ArXiv, etc.)
  163. - Returns detailed paper metadata with nested field support
  164. - `paper_batch_details`: Efficiently retrieve details for multiple papers
  165. - Accepts up to 1000 paper IDs per request
  166. - Supports the same ID formats and fields as single paper details
  167. - `paper_authors`: Get the authors associated with a specific paper
  168. - Returns paginated author results for the paper
  169. - Supports author field customization with offset and limit controls
  170. - `paper_autocomplete`: Get paper title suggestions for a partial query
  171. - Returns minimal paper metadata for interactive search completion
  172. - Truncates overly long queries to the API-supported length
  173. - `snippet_search`: Search within paper snippets and excerpts
  174. - Returns relevant text matches from titles, abstracts, and body text
  175. - Supports filters for paper IDs, authors, venue, year, and field of study
  176. ### Citation Tools
  177. - `paper_citations`: Get papers that cite a specific paper
  178. - Returns paginated list of citing papers
  179. - Includes citation context when available
  180. - Supports field customization and sorting
  181. - `paper_references`: Get papers referenced by a specific paper
  182. - Returns paginated list of referenced papers
  183. - Includes reference context when available
  184. - Supports field customization and sorting
  185. ### Author Tools
  186. - `author_search`: Search for authors by name
  187. - Returns paginated results with customizable fields
  188. - Includes affiliations and publication counts
  189. - `author_details`: Get detailed information about an author
  190. - Returns comprehensive author metadata
  191. - Includes metrics like h-index and citation counts
  192. - `author_papers`: Get papers written by an author
  193. - Returns paginated list of author's publications
  194. - Supports field customization and sorting
  195. - `author_batch_details`: Get details for multiple authors
  196. - Efficiently retrieve information for up to 1000 authors
  197. - Returns the same fields as single author details
  198. ### Recommendation Tools
  199. - `get_paper_recommendations_single`: Get recommendations based on a single paper
  200. - Returns similar papers based on content and citation patterns
  201. - Supports field customization for recommended papers
  202. - `get_paper_recommendations_multi`: Get recommendations based on multiple papers
  203. - Accepts positive and negative example papers
  204. - Returns papers similar to positive examples and dissimilar to negative ones
  205. ## Usage Examples
  206. ### Basic Paper Search
  207. ```python
  208. results = await paper_relevance_search(
  209. context,
  210. query="machine learning",
  211. year="2020-2024",
  212. min_citation_count=50,
  213. fields=["title", "abstract", "authors"]
  214. )
  215. ```
  216. ### Paper Recommendations
  217. ```python
  218. # Single paper recommendation
  219. recommendations = await get_paper_recommendations_single(
  220. context,
  221. paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
  222. fields="title,authors,year"
  223. )
  224. # Multi-paper recommendation
  225. recommendations = await get_paper_recommendations_multi(
  226. context,
  227. positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
  228. negative_paper_ids=["ArXiv:1805.02262"],
  229. fields="title,abstract,authors"
  230. )
  231. ```
  232. ### Batch Operations
  233. ```python
  234. # Get details for multiple papers
  235. papers = await paper_batch_details(
  236. context,
  237. paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
  238. fields="title,authors,year,citations"
  239. )
  240. # Get details for multiple authors
  241. authors = await author_batch_details(
  242. context,
  243. author_ids=["1741101", "1780531"],
  244. fields="name,hIndex,citationCount,paperCount"
  245. )
  246. ```
  247. ## Error Handling
  248. The server provides standardized error responses:
  249. ```python
  250. {
  251. "error": {
  252. "type": "error_type", # rate_limit, api_error, validation, timeout
  253. "message": "Error description",
  254. "details": {
  255. # Additional context
  256. "authenticated": true/false # Indicates if request was authenticated
  257. }
  258. }
  259. }
  260. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.