# Academic Search MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets Claude Code
(or any MCP client) search academic literature through the [Semantic Scholar](https://www.semanticscholar.org)
API. It is built for research workflows: relevance search with filters, batch metadata retrieval,
and citation-graph recommendations.

This is a modified fork of [afrise/academic-search-mcp-server](https://github.com/afrise/academic-search-mcp-server).
The server was rewritten on top of the official [`semanticscholar`](https://pypi.org/project/semanticscholar/)
Python library and extended with batch and recommendation tools, bounded retry on rate limits, and
clearer error handling. See [Changes from upstream](#changes-from-upstream) below.

## Tools

| Tool | What it does |
|------|--------------|
| `search_papers` | Relevance search with optional filters: `year`, `fields_of_study`, `min_citation_count`, `venue`, `open_access_pdf`. |
| `search_by_topic` | Same as `search_papers`, with a `year_start`/`year_end` range (kept for backward compatibility). |
| `fetch_paper_details` | Full metadata for a single paper by Semantic Scholar ID, DOI, or arXiv ID. |
| `get_papers_batch` | Details for up to **500 papers in one request** — far cheaper than looping `fetch_paper_details` under the 1 req/sec limit. |
| `recommend_papers` | Citation-graph recommendations from seed paper IDs (`positive_paper_ids`, optional `negative_paper_ids`). Surfaces structurally similar work that keyword search misses. |

Each tool returns a formatted text block per paper: ID, title, authors, year, DOI, venue, citation
count, fields of study, open-access status, PDF URL, abstract, and TL;DR when available.

## Requirements

- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** (recommended) — or plain `pip`
- A **Semantic Scholar API key is optional** (see below)

## Install

```bash
git clone https://github.com/ociupitu/academic-search-mcp.git
cd academic-search-mcp
uv sync          # creates .venv and installs dependencies from uv.lock
```

Prefer pip? `pip install -e .` inside a virtual environment works too.

## API key (optional)

The server reads `SEMANTIC_SCHOLAR_API_KEY` from the environment, but **it is optional**:

- **Without a key** — requests go through Semantic Scholar's shared anonymous pool. It works, but
  you are more likely to hit `HTTP 429` rate limiting during busy periods.
- **With a free key** — you get your own quota. Register at
  <https://www.semanticscholar.org/product/api> and set the variable (the `.mcp.json` example below
  wires it in).

Either way the server keeps requests sequential and does a short **bounded retry** on a 429, then
returns a readable `Error:` string rather than hanging or silently returning "no results".

## Use with Claude Code

Add the server to your client's MCP config (for Claude Code, a `.mcp.json` in your project root).
Point `--directory` at wherever you cloned this repo, and use an **absolute path**:

```json
{
  "mcpServers": {
    "academic-search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/academic-search-mcp", "server.py"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

Leave the `env` block out entirely to run keyless. Restart your MCP client after editing the config.

## Changes from upstream

- Rewritten on the official `semanticscholar` library instead of hand-rolled `httpx` calls.
- Added `get_papers_batch` (batch details) and `recommend_papers` (citation-graph recommendations).
- Added search filters: `fields_of_study`, `min_citation_count`, `venue`, `open_access_pdf`, and a
  flexible `year` range.
- Fail-fast client (`retry=False`) plus a bounded in-server retry on 429, so a throttle recovers in
  seconds or returns a clean error instead of blocking for minutes.
- Dropped the Crossref path; Semantic Scholar is the single source.

## License

**AGPL-3.0**, inherited from the upstream project. See [LICENSE](LICENSE). If you redistribute or
run a modified version as a network service, the AGPL's source-availability terms apply.