Semantic Scholar MCP Server

An unofficial, community-maintained toolkit for the public Semantic Scholar APIs: a Model Context Protocol server, two CLIs, and two independently installable agent skills.

Version 2.3.0 provides 20 endpoint-aligned operations, two backward-compatible operations, a schema-driven endpoint CLI, an evidence-oriented ScholarQA CLI, and separate skills for endpoint routing and research synthesis.

Why this exists

Language-model agents often understand the research task but call the wrong API surface. Typical failures include using generic paper search for an exact-title lookup, treating autocomplete as evidence, confusing recommendations with citation edges, inventing unsupported endpoint names, or sending fields and pagination parameters to operations that do not accept them.

Raw REST documentation leaves endpoint selection, argument construction, and response handling to the model. This project separates those concerns into composable layers:

1. MCP server: exposes typed tool schemas directly to MCP-capable clients.

2. Endpoint CLI: lets shell-based agents inspect and call those same 22 operations with validated JSON.

3. ScholarQA CLI: collects auditable multi-query evidence bundles and batch-verifies citations without embedding an LLM provider.

4. Two agent skills: one teaches exact endpoint routing; the other teaches attributed evidence synthesis and research ideation.

The endpoint MCP and CLI share the same FastMCP definitions. The ScholarQA CLI uses the same direct API client but adds a bounded evidence workflow. Skills contain agent instructions, not another API implementation.

Related MCP server: McpDeepResearch

Choose the pieces you need

The similarly named CLI and skill are deliberately separate:

Common combinations:

Neither skill requires the other. The Python package installs all three executables, so one package can support any runtime combination. npx skills installs only the selected skill instructions.

scholarqa-cli intentionally stops at model-free evidence collection and citation verification. The agent using $scholarqa-research performs the reasoning and prose synthesis, so the CLI does not require a second model API key or hide unsupported claims inside an opaque generation step.

Highlights

• Broad API coverage: authors, papers, citations, references, full-text snippets, recommendations, and dataset releases.

• No Semantic Scholar SDK dependency: the server uses a small asynchronous httpx client and depends only on mcp and httpx.

• Native responses: endpoint-aligned tools preserve Semantic Scholar's JSON response shape instead of converting it into a reduced local model.

• Explicit pagination: callers control offsets or continuation tokens; the server never silently crawls an unbounded result set.

• Rate-limit aware: HTTP 429 and transient 5xx responses use Retry-After when available and bounded exponential backoff otherwise.

• Shared endpoint contract: MCP and semanticscholar-cli use the same tool names, schemas, validation, and API client.

• Auditable QA bundles: scholarqa-cli records queries, filters, raw results, candidate IDs, partial failures, and evidence-level guidance.

• Agent-ready skills: semantic-scholar-cli provides strict endpoint routing, while scholarqa-research provides attributed, evidence-first synthesis and ideation.

• Installable distribution: the release ZIP installs semanticscholar-mcp, semanticscholar-cli, and scholarqa-cli.

• Offline tests: the test suite uses an in-memory HTTP transport and does not consume Semantic Scholar API quota.

Requirements

• Python 3.10 or later

• An MCP client that supports stdio servers, if using the MCP transport

• Optional: a Semantic Scholar API key for a dedicated rate limit

Anonymous requests work for many endpoints, but they use a heavily shared rate limit.

Quick start

Ask Codex or Claude Code to install it

Send the following entire message to your coding agent rather than only its first line. It deliberately requires the agent to ask which form you want before changing your environment:

Install this Semantic Scholar MCP / CLI / skill toolkit for me:
https://github.com/XWang20/semanticscholar-MCP-Server

Before making any changes, first ask me which form I want:
1. MCP server
2. semanticscholar-cli (exact endpoint CLI)
3. scholarqa-cli (evidence collection and citation verification CLI)
4. semantic-scholar-cli skill (endpoint routing instructions)
5. scholarqa-research skill (research QA and ideation instructions)
6. a combination of these components

Do not choose for me and do not begin installation until I answer. After I answer,
detect whether you are running in Codex or Claude Code, follow the repository README,
ask whether the installation should be project-local or global when relevant, explain any
runtime a selected skill needs, and verify the selected components without exposing or
committing an API key.

中文版本：

为我安装这个 Semantic Scholar MCP / CLI / skill 工具集：
https://github.com/XWang20/semanticscholar-MCP-Server

开始任何更改之前，先问我要安装哪一种形式：
1. MCP server
2. semanticscholar-cli（精确端点 CLI）
3. scholarqa-cli（证据收集与引用核验 CLI）
4. semantic-scholar-cli skill（端点路由指令）
5. scholarqa-research skill（研究问答与研究构思指令）
6. 这些组件的组合

不要替我选择，也不要在我回答前开始安装。得到确认后，再判断你当前运行在
Codex 还是 Claude Code 中；按照仓库 README 安装；如果涉及安装范围，再询问
是项目级还是全局安装；说明所选 skill 需要的 runtime；最后验证所选组件，
并且不要泄露或提交 API key。

Install a release ZIP

python -m venv .venv
source .venv/bin/activate
python -m pip install ./semanticscholar-mcp-server-2.3.0.zip

The package installs all three entry points:

semanticscholar-mcp
semanticscholar-cli tools
scholarqa-cli --help

Install from a source checkout

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

You can then use the console entry points above or run a module directly:

python semantic_scholar_server.py
python scholarqa_cli.py --help

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

Endpoint CLI: semanticscholar-cli

The CLI intentionally does not invent a second set of friendly-but-different command names. It exposes the same 22 operation names and JSON schemas as MCP.

List operations:

semanticscholar-cli tools
semanticscholar-cli tools --json

Inspect one operation before calling it:

semanticscholar-cli schema search_semantic_scholar_papers

Call an operation with a JSON object:

semanticscholar-cli call search_semantic_scholar_papers \
  --params '{"query":"retrieval augmented generation","open_access_pdf":true,"limit":5}'

For larger inputs, use --params-file params.json or --params - to read JSON from stdin. Add --compact for single-line output.

Endpoint CLI exit statuses are designed for agents and scripts:

Research QA CLI: scholarqa-cli

The ScholarQA CLI prepares evidence for an agent; it does not generate a final answer. collect runs complementary snippet and paper searches for each query and emits one JSON bundle:

scholarqa-cli collect "Does retrieval-augmented generation reduce factual errors?" \
  --query "retrieval augmented generation factuality evaluation" \
  --query "RAG hallucination benchmark" \
  --year "2020-" > evidence.json

After the agent selects the papers that support its material claims, verify their canonical records:

scholarqa-cli verify ARXIV:2005.11401 DOI:10.1145/3786335.3813161 \
  > verified.json

IDs can also be provided as a JSON array or one ID per line with --ids-file FILE; use --ids-file - for stdin. Show the methodology sources and adaptation boundary with:

scholarqa-cli provenance

For collect, status 0 means all searches succeeded, status 1 means the JSON bundle contains usable partial results plus operation_errors, and status 2 means invalid input or a local failure. For verify, status 0 means every ID resolved and status 1 means at least one ID was unresolved or the upstream batch request failed. Both commands use 130 for interruption.

Agent skills

The repository contains two Agent Skills-compatible skills. They can be installed and used separately:

scholarqa-cli and scholarqa-research form an independent Semantic Scholar adaptation, not the official Ai2 Scholar QA implementation. The evidence-QA workflow credits the Ai2 Scholar QA paper and official allenai/ai2-scholarqa-lib repository. The ideation workflow credits the Scideator paper. See the skill's provenance reference and third-party notices for scope, licenses, and adaptation boundaries. No upstream ScholarQA code or runtime dependency is bundled.

Install with npx skills

List the available skills:

npx skills add XWang20/semanticscholar-MCP-Server --list

Install either skill for the current project; the installer detects supported agents:

npx skills add XWang20/semanticscholar-MCP-Server \
  --skill semantic-scholar-cli

npx skills add XWang20/semanticscholar-MCP-Server \
  --skill scholarqa-research

Install both together:

npx skills add XWang20/semanticscholar-MCP-Server \
  --skill semantic-scholar-cli --skill scholarqa-research

Or install either skill globally for a specific agent:

# Codex
npx skills add XWang20/semanticscholar-MCP-Server \
  --skill scholarqa-research --global --agent codex

# Claude Code
npx skills add XWang20/semanticscholar-MCP-Server \
  --skill scholarqa-research --global --agent claude-code

npx skills installs skill instructions only. It does not install the Python package or configure an MCP client. Install the Python package when the endpoint skill needs semanticscholar-cli, or when the research skill will use scholarqa-cli. The research skill may instead use an already configured MCP runtime.

Install the skill manually

Extract the standalone skill ZIP into the appropriate global skills directory, or copy the source directory directly:

# Codex
unzip semantic-scholar-cli-skill-1.1.0.zip -d ~/.codex/skills
unzip scholarqa-research-1.1.0.zip -d ~/.codex/skills

# Claude Code
unzip semantic-scholar-cli-skill-1.1.0.zip -d ~/.claude/skills
unzip scholarqa-research-1.1.0.zip -d ~/.claude/skills

# Or, from a source checkout (Codex examples):
cp -R skills/semantic-scholar-cli ~/.codex/skills/
cp -R skills/scholarqa-research ~/.codex/skills/

Invoke a skill explicitly, for example:

Use $semantic-scholar-cli to find recent open-access papers about retrieval-augmented generation and verify the final paper records.

Use $scholarqa-research to synthesize the evidence for whether retrieval-augmented generation reduces factual errors, with verified citations and limitations.

semantic-scholar-cli expects semanticscholar-cli and can use python semantic_scholar_cli.py during local development. scholarqa-research can use either scholarqa-cli (python scholarqa_cli.py in a checkout) or the connected MCP server. Install both skills only when the task benefits from both high-level research synthesis and low-level endpoint control.

MCP client configuration

After installing the package, configure your MCP client with the absolute path to the virtual environment's console script:

{
  "mcpServers": {
    "semanticscholar": {
      "command": "/absolute/path/to/.venv/bin/semanticscholar-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-optional-api-key"
      }
    }
  }
}

For a source checkout without package installation:

{
  "mcpServers": {
    "semanticscholar": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/semantic_scholar_server.py"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-optional-api-key"
      }
    }
  }
}

Do not commit an API key to an MCP configuration stored in a public repository. Prefer your client's secret or environment-variable mechanism when available.

Example requests

Once the MCP server, CLI, or corresponding skills are available, an assistant can handle requests such as:

• “Find recent open-access papers about retrieval-augmented generation.”

• “Resolve this DOI and return its references with citation contexts.”

• “Recommend papers similar to these two papers but unlike this negative example.”

• “Search full-text snippets for evidence about calibration in scientific QA.”

• “List the datasets in the latest Semantic Scholar dataset release.”

• “Synthesize the evidence across these papers, cite every material claim, and surface disagreements.”

• “Generate facet-grounded research ideas from these seed papers, then check novelty against retrieved literature.”

The exact natural-language workflow depends on the agent. MCP exposes typed tools, semanticscholar-cli exposes the same endpoint schemas to shell agents, and scholarqa-cli packages evidence for the research skill to synthesize.

Configuration

Tool catalog

Academic Graph API

Paper search exposes publication type, open-access, minimum citation count, publication date/year, venue, and field-of-study filters. Bulk search uses token pagination and supports sorting. Citation and reference tools can request citation contexts, intents, context/intent pairs, and influential-citation status.

Recommendations API

Single-paper recommendations support the recent and all-cs pools. Multi-paper recommendations accept positive and optional negative paper IDs. The API returns at most 500 recommendations per request.

Datasets API

Dataset tools return release metadata and temporary download URLs. They do not automatically download multi-gigabyte datasets. The identifier latest is accepted wherever the upstream API supports it.

Backward-compatible tools

Two tool names are retained for clients built against the original project:

New integrations should use the endpoint-aligned search, citation, and reference tools because they expose filters, fields, and independent pagination.

Paper identifiers and response fields

Paper tools accept identifiers supported by Semantic Scholar, including:

• Semantic Scholar paper ID

• CorpusId:

• DOI:

• ARXIV:

• ACL:

• MAG:

• PMID: and PMCID:

• supported Semantic Scholar paper URLs

Most tools accept a fields list. Useful paper fields include abstract, authors, externalIds, openAccessPdf, tldr, journal, citationStyles, s2FieldsOfStudy, and embedding.

Default field sets are intentionally rich but exclude the large embedding vector. Request it explicitly when needed:

{
  "paper_id": "ARXIV:2005.11401",
  "fields": ["paperId", "title", "embedding"]
}

Pagination, retries, and errors

• Offset-paginated tools return only the requested page.

• Bulk paper search returns the upstream continuation token; pass it back to request the next page.

• The server honors Retry-After for throttled responses and otherwise uses bounded exponential backoff.

• Validation, upstream HTTP, and unexpected transport failures are returned as {"error": "..."} so one failed request does not terminate the MCP server.

• The CLI prints the same normalized JSON and returns a nonzero exit status for API or schema errors.

• A successful empty result is returned unchanged and is not converted into an error.

Semantic Scholar can change limits or schemas independently of this project. Consult the official API documentation when an upstream validation rule differs from the server's current defaults.

Security and data handling

• Queries, identifiers, filters, and requested fields are sent to the configured Semantic Scholar API origin.

• The API key is used only as the x-api-key request header.

• The server does not persist API responses, maintain a paper database, or automatically download dataset files.

• Avoid placing secrets in prompts, search queries, logs, issues, or public MCP configuration files.

• Dataset download URLs can be temporary and should be treated accordingly.

If you discover a security issue, do not publish credentials or exploit details in a public issue. Use the repository owner's private security-reporting channel; if none is listed, open a minimal issue requesting private contact without disclosing the vulnerability.

Development

Create a development environment and install the project in editable mode:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Run the complete test suite:

python -m unittest discover -v

The tests use httpx.MockTransport; they do not call the live Semantic Scholar API or consume rate-limit quota.

Project layout

semantic_scholar_api.py       Async HTTP client, validation, retries, and API paths
semantic_scholar_cli.py       Schema inspection and JSON command-line dispatch
semantic_scholar_server.py    FastMCP server and 22 registered tools
scholarqa_cli.py               Evidence-bundle collection and citation verification
skills/semantic-scholar-cli/  Endpoint-routing skill for shell-based agents
skills/scholarqa-research/    Attributed evidence synthesis and ideation skill
tests/                        Offline API, CLI, and tool-registration tests
pyproject.toml                Package metadata and three console entry points
requirements.txt              Minimal runtime dependencies
THIRD_PARTY_NOTICES.md        ScholarQA and Scideator attribution boundaries

Contribution guidelines

Contributions are welcome. A change should:

1. Preserve the upstream JSON response shape for endpoint-aligned tools.

2. Keep pagination explicit and bounded.

3. Add or update offline tests for endpoint paths, parameters, payloads, CLI behavior, and tool registration.

4. Avoid adding a heavyweight API SDK when the direct client can support the operation clearly.

5. Never include API keys, generated bytecode, virtual environments, or large downloaded datasets.

6. Run python -m unittest discover -v before opening a pull request.

For new upstream endpoints, update the client method, MCP tool, tool-registration test, skill routing reference, and this catalog together. The CLI discovers the MCP schema automatically and should not maintain a separate endpoint registry.

API references

• Academic Graph API

• Recommendations API

• Datasets API

• Semantic Scholar API overview

• Model Context Protocol

Project lineage

Version 2 is a substantial rewrite and expansion of JackKuo666/semanticscholar-MCP-Server. It replaces the original SDK-backed runtime with a direct asynchronous API client, expands coverage from four tools to 22, preserves native responses, and adds pagination, retry handling, tests, and packaging.

The two original high-level tool names listed under backward compatibility remain available so existing clients can migrate gradually. Repository history and this attribution are retained in recognition of the original work.

License

Distributed under the MIT License.

Research workflows and adapted third-party material retain their original attribution and license boundaries as documented in THIRD_PARTY_NOTICES.md. In particular, this repository does not relicense or claim authorship of Ai2 Scholar QA or Scideator.

“Semantic Scholar” is used only to identify compatibility with the public service. This project does not claim ownership of the Semantic Scholar name, API, data, or trademarks.