Academic Search

A Model Context Protocol (MCP) server that lets Claude Code (or any MCP client) search academic literature through the Semantic Scholar 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. The server was rewritten on top of the official semanticscholar Python library and extended with batch and recommendation tools, bounded retry on rate limits, and clearer error handling. See 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 (recommended) — or plain pip
• A Semantic Scholar API key is optional (see below)

Install

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:

{
  "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. If you redistribute or run a modified version as a network service, the AGPL's source-availability terms apply.