# semanticscholar-mcp

[Polski](README.pl.md)

Semantic Scholar Academic Graph API via MCP.

## Table of contents

- [Tools](#tools)
- [Environment variables](#environment-variables)
- [Wiring it up](#wiring-it-up)
- [Local run](#local-run)

## Tools

| Tool | Parameters | Description |
|------|-----------|------|
| `search_papers` | `query, fields, year, venue, fields_of_study, open_access_pdf, min_citation_count, publication_types, limit, offset` | Relevance-ranked paper search |
| `search_papers_bulk` | `query, fields, year, venue, sort, publication_types, fields_of_study, token` | Bulk paper search (up to 1000/call, with continuation token) |
| `match_paper_title` | `query, fields` | Find the paper whose title best matches a query |
| `autocomplete_paper` | `query` | Suggest paper title completions |
| `get_paper` | `paper_id, fields` | Details about a single paper |
| `get_papers_batch` | `paper_ids, fields` | Details for up to 500 papers at once |
| `get_paper_authors` | `paper_id, fields, limit, offset` | Authors of a given paper |
| `get_paper_citations` | `paper_id, fields, limit, offset` | Papers that cite a given paper |
| `get_paper_references` | `paper_id, fields, limit, offset` | Papers referenced by a given paper |
| `search_authors` | `query, fields, limit, offset` | Search for authors by name |
| `get_author` | `author_id, fields` | Details about a single author |
| `get_author_papers` | `author_id, fields, limit, offset` | Papers written by a given author |
| `get_authors_batch` | `author_ids, fields` | Details for up to 1000 authors at once |
| `search_snippets` | `query, paper_ids, fields_of_study, venue, publication_types, insertion_ids, min_citation_count` | Search text snippets from paper full texts, abstracts, and titles |

All Semantic Scholar API calls are throttled to 1 request per second, cumulative across all tools, per the API's rate limit.

## Environment variables

| Variable | Required | Description |
|---------|----------|------|
| `S2_API_KEY` | yes | Semantic Scholar API key, sent as the `x-api-key` header |

## Wiring it up

Only requirement: `uv` (https://docs.astral.sh/uv/). Nothing else to install.

### Claude Code

```
claude mcp add semanticscholar-mcp -e S2_API_KEY=<value> -- uvx --from git+https://github.com/dam2452/semanticscholar-mcp.git semanticscholar-mcp
```

### Claude Desktop / other MCP client

```json
{
  "mcpServers": {
    "semanticscholar-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dam2452/semanticscholar-mcp.git", "semanticscholar-mcp"],
      "env": { "S2_API_KEY": "<value>" }
    }
  }
}
```

After pushing a new version: `uv cache clean` and restart the client.

## Local run

```
uv run --directory . semanticscholar-mcp
```

Tests (manual):

```
uv run --directory . --with pytest pytest test/
```