Skip to main content
Glama
semanticscholar-mcp

semanticscholar-mcp

by dam2452
README.md
# 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/
```

TDQS

A3.6/5.0

Scored across 14 tools

Disambiguation5/5

Each tool targets a distinct operation: search vs. retrieval vs. authors vs. references/citations. Even the search variants (search_papers, search_papers_bulk, match_paper_title, autocomplete_paper) are clearly differentiated by their descriptions—relevance ranking, bulk output, exact title match, and title completion.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (get_, search_, match_, autocomplete_). Plural/singular usage is logical (get_paper vs get_papers_batch) and the bulk suffix is uniformly applied.

Tool Count5/5

14 tools is well within the ideal range for a scholarly data API. Each tool covers a meaningful aspect of paper and author retrieval, with bulk and single-item variants earning their place.

Completeness5/5

The tool surface covers the full read-only lifecycle: paper search, paper details, references, citations, author search, author details, author papers, and bulk operations. No obvious dead ends or missing operations for the stated domain.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues