[![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)

# Semantic Scholar MCP Server

[![smithery badge](https://smithery.ai/badge/semantic-scholar-fastmcp-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
        }
    }
}
```