# Semantic Scholar MCP Server

An [MCP](https://modelcontextprotocol.io/) server that provides access to the [Semantic Scholar](https://www.semanticscholar.org/) academic paper API, with optional [ngrok](https://ngrok.com/) tunnel for remote access.

## Features

- **search_papers** — Search for papers by keyword, year, field of study, and citation count
- **get_paper** — Get full details for a paper by S2 ID, DOI, ArXiv ID, etc.
- **get_citations** — List papers that cite a given paper
- **get_references** — List papers referenced by a given paper
- **search_authors** — Search for authors by name
- **get_author** — Get author profile (h-index, paper count, affiliations)
- **get_author_papers** — List papers by a specific author
- **recommend_papers** — Get paper recommendations based on a seed paper
- **batch_get_papers** — Look up multiple papers in a single request

## Setup

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

```bash
# Install dependencies
uv sync
```

Optionally set an API key for higher rate limits:

```bash
export S2_API_KEY="your-key-here"
```

## Usage

### HTTP transport (default) — for remote clients

```bash
uv run python server.py
```

The server listens on `http://localhost:8000`. The MCP endpoint is at `/mcp`.

### With ngrok tunnel

```bash
uv run python server.py --ngrok
```

This opens a public ngrok tunnel and prints the URL to stderr.

### stdio transport — for Claude Desktop

```bash
uv run python server.py --transport stdio
```

Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uv",
      "args": ["--directory", "/path/to/this/project", "run", "python", "server.py", "--transport", "stdio"]
    }
  }
}
```

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--transport` | `streamable-http` | `streamable-http` or `stdio` |
| `--port` | `8000` | Port for HTTP transport |
| `--ngrok` | off | Open an ngrok tunnel |