Skip to main content
Glama
niol-zh

research-mcp

by niol-zh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

research-mcp

CI License: MIT

An MCP server for academic literature research. It combines a Scopus search with three free, open scholarly APIs so you get abstracts, author metrics and open-access PDFs without needing institutional Scopus entitlements.

What it does

Tool

Data source

Returns

search_scopus

Elsevier Scopus

Documents matching a query (title, DOI, citations, …)

get_abstract_details

Scopus + CrossRef

Metadata + abstract text

get_author_profile

OpenAlex

h-index, citation count, paper count, affiliations, ORCID

get_citing_papers

OpenAlex (default) or Scopus

Papers that cite a given document (forward citations)

get_references

OpenAlex + CrossRef

Papers cited by a given document (backward citations)

assess_relevance

OpenAlex

Abstract, topics, keywords and term overlap for screening papers against a research context

get_pdf_link

Unpaywall

Open-access PDF link for a DOI

get_quota_status

—

Reminder about Scopus API quota

Citation traversal in both directions

get_citing_papers (forward) and get_references (backward) let you walk a citation graph from any starting paper. Both directions rely on OpenAlex, because a free Scopus key can serve neither:

  • backward — view=REF returns 401 AUTHORIZATION_ERROR

  • forward — REFEID() is a restricted search field and returns 400 INVALID_INPUT

OpenAlex covers both for free, with no quota and generally wider recall, so it is the default for each. Pass a DOI and citation traversal costs no Scopus calls at all.

Screening papers for relevance

assess_relevance takes a list of papers and a plain-language research context, and returns the evidence needed to judge each one: the abstract (from OpenAlex, which covers far more papers than CrossRef), scored topics and keywords, and which of your context's terms appear or are missing.

It screens up to 25 papers in a single call, so a whole search_scopus result set can be triaged in one turn instead of one lookup per paper.

It deliberately returns no verdict and no relevance score. The server has no language model; the judgement is left to the model calling the tool, which reads the abstract itself. The lexical_overlap field is a raw word-match signal that ignores synonyms and meaning — useful supporting evidence, not a ranking.

Why the extra APIs?

A free Scopus API key only grants the search endpoint. The Abstract Retrieval (view=FULL) and Author Retrieval endpoints require an institutional subscription and otherwise return 401 AUTHORIZATION_ERROR. To stay useful for everyone, this server falls back to:

  • CrossRef for abstract text (free, no key)

  • OpenAlex for author metrics incl. h-index (free, no key)

  • Unpaywall for legal open-access PDFs (free, no key)

If you do have institutional Scopus access, the Scopus calls simply return richer data.

Related MCP server: Academic Paper MCP HTTP/SSE Server

Requirements

  • Python ≥ 3.10

  • A free Scopus API key — register at dev.elsevier.com

  • Dependencies: only mcp and httpx

Getting an Elsevier (Scopus) API key

The Scopus tools need an Elsevier Developer API key. It's free to register.

Step by step

  1. Create an Elsevier account. Go to dev.elsevier.com and click "I want an API Key". Sign in, or register a free account (the same account works across Elsevier products such as ScienceDirect and Mendeley).

  2. Open the API Key management page. Once signed in, go to dev.elsevier.com/apikey/manage.

  3. Create a new key. Click "Create API Key" and fill in:

    • Label — any name, e.g. research-mcp.

    • Website URL — required by the form but not validated for server use. You can enter http://localhost or your GitHub repo URL.

    • Optionally a CORS domain — leave blank for server-side use.

  4. Accept the agreements. Tick the API Service Agreement and the text & data mining policy, then submit.

  5. Copy the key. A 32-character hexadecimal key appears (e.g. 1a2b3c4d5e6f...). This is your SCOPUS_API_KEY. You can return to the manage page anytime to view or revoke it.

What the free key can and cannot do

Capability

Free key

Notes

search_scopus

✅

Up to ~20,000 requests/week

get_citing_papers

✅

Via the default source="openalex" — free, no quota

Scopus forward citations (REFEID())

❌

Restricted search field → HTTP 400 INVALID_INPUT; needs an institutional subscription

get_references

✅

Uses OpenAlex/CrossRef, not Scopus — no quota at all

assess_relevance

✅

Uses OpenAlex — no quota (unless you pass Scopus IDs)

Scopus full abstract (view=FULL)

❌

Needs institutional subscription → this server falls back to CrossRef

Scopus reference list (view=REF)

❌

Needs institutional subscription → get_references uses OpenAlex

Scopus author retrieval

❌

Needs institutional subscription → this server uses OpenAlex

get_journal_metrics

⚠️

Uses the Serial Title API, which is entitlement-gated. Without it the tool falls back to a local Scimago table

Unlocking full Scopus data (optional)

The richer Scopus endpoints are gated by your institution's subscription, not by the key tier. To use them:

  • Register / use the key from your institution's network. Elsevier binds entitlements to the institutional IP range. Create or first-use the key while on campus Wi-Fi or your university VPN.

  • Alternatively, request an Institutional Token from your library and set it via the X-ELS-Insttoken header (not currently wired into this server — open an issue if you need it).

Without institutional access the server still works fully: abstracts come from CrossRef, author metrics from OpenAlex, and PDFs from Unpaywall.

Quota & fair use

  • Watch your weekly quota — every call returns X-RateLimit-Remaining headers.

  • Don't hammer the API in tight loops; the search tools cap at 25 results per call by design.

  • The key is a secret. Keep it in the env block of your MCP config, never commit it to git (this repo's .gitignore already excludes .env and keys).

Installation

Option A — One-click install (.mcpb bundle, recommended)

Every release ships a research-mcp-vX.Y.Z.mcpb bundle. Download it and double-click, or drag it into Claude Desktop's Settings window. Claude Code and MCP for Windows install it too.

The bundle asks for your Scopus API key and contact email in a form — the key is stored masked, so there is no config file to hand-edit and no environment variable to set.

It carries no Python dependencies: the bundle declares the uv runtime, and the host resolves mcp and httpx at first launch. That keeps it at ~23 KB and platform-independent — vendoring would not work here, because the MCP SDK depends on the compiled pydantic-core, which cannot be bundled portably across macOS, Windows and Linux.

Option B — Claude Code / Claude Desktop, configured by hand (no server needed)

This is the simplest path. The server runs locally as a stdio process — uvx fetches it straight from GitHub, so there is no web server and no tunnel involved.

Add this to your MCP config (~/.claude.json, or the Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/niol-zh/research-mcp", "research-mcp"],
      "env": {
        "SCOPUS_API_KEY": "your-scopus-api-key",
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Restart Claude. That's it — uvx installs mcp + httpx in an isolated environment automatically.

UNPAYWALL_EMAIL is required for the get_pdf_link tool. Unpaywall rejects requests without a real contact email (HTTP 422). Use your own address. All other tools work without it.

Local clone instead of GitHub

If you've cloned the repo and want to run from disk:

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["--from", "/path/to/research-mcp", "research-mcp"],
      "env": { "SCOPUS_API_KEY": "your-scopus-api-key" }
    }
  }
}

Option C — Claude Cowork (remote connector, needs an HTTPS URL)

Cowork runs in an isolated cloud VM and cannot reach a local stdio process. It needs the server exposed over HTTPS using the Streamable HTTP transport. The easiest way is a free Cloudflare Quick Tunnel.

You need two pieces running on your machine:

  1. mcp-proxy — wraps the stdio server as a local HTTP server

  2. cloudflared — exposes that local port over a public HTTPS URL

1. Install the helpers

# mcp-proxy comes via uvx, no install needed
# cloudflared:
#   Windows:  download cloudflared.exe from
#             https://github.com/cloudflare/cloudflared/releases/latest
#   macOS:    brew install cloudflared
#   Linux:    see Cloudflare docs

2. Start the HTTP server (terminal 1)

export SCOPUS_API_KEY="your-scopus-api-key"
export UNPAYWALL_EMAIL="you@example.com"

# --with "mcp<2": uvx resolves mcp-proxy in its own environment, so the cap in
# pyproject.toml does not reach it. Without the pin it pulls mcp 2.x, which no
# longer exports request_ctx, and mcp-proxy dies on import.
uvx --with "mcp<2" mcp-proxy --port 8000 --transport streamablehttp \
  -e SCOPUS_API_KEY "$SCOPUS_API_KEY" \
  -- uvx --from git+https://github.com/niol-zh/research-mcp research-mcp

3. Open the tunnel (terminal 2)

cloudflared tunnel --url http://localhost:8000

Cloudflare prints a URL like https://random-words.trycloudflare.com.

4. Add the connector in Cowork

  • Customize → Connectors → Add custom connector

  • Name: Research

  • Remote MCP server URL: https://random-words.trycloudflare.com/mcp (note the /mcp suffix)

⚠️ A Quick Tunnel URL is temporary — it changes every time you restart cloudflared, and both terminals must stay open while you use Cowork. For a stable URL, deploy the server to a host (Railway, Render, Fly.io, a VPS) or use a named Cloudflare Tunnel.

Windows users: the repo includes scripts/start-tunnel.ps1, which starts the server and the tunnel and copies the connector URL to your clipboard (requires uvx and cloudflared on PATH):

$env:SCOPUS_API_KEY = "your-key"
$env:UNPAYWALL_EMAIL = "you@example.com"
./scripts/start-tunnel.ps1

Example

A typical research flow in Claude, chaining several tools in one turn:

You: How influential is Amy Edmondson's work, and can you get me an open-access PDF of a recent open-science paper to read?

1. get_author_profile("Amy Edmondson") → OpenAlex returns disambiguated matches with metrics:

{
  "matches": [
    {
      "openalex_id": "A5003931866",
      "name": "Amy C. Edmondson",
      "h_index": 66,
      "citation_count": 45902,
      "paper_count": 358,
      "i10_index": 132,
      "affiliations": ["Harvard University"],
      "orcid": "0000-0003-4409-913X",
      "url": "https://openalex.org/A5003931866"
    }
  ],
  "note": "Top 3 matches from OpenAlex — verify by name/affiliation."
}

2. get_pdf_link("10.1371/journal.pone.0173664") → Unpaywall finds a gold open-access PDF:

{
  "doi": "10.1371/journal.pone.0173664",
  "oa_pdf_url": "https://journals.plos.org/plosone/article/file?id=10.1371/journal.pone.0173664&type=printable",
  "oa_status": "gold",
  "source": "publisher",
  "journal_is_oa": true
}

Claude: Amy C. Edmondson (Harvard) has an h-index of 66 across 358 papers with ~45,900 citations — exceptionally influential in organizational behavior. Here is an open-access PDF you can read: [link].

Every tool returns indented JSON, so Claude parses the fields reliably and combines results across calls. A full literature search would add search_scopus (to find papers) and get_abstract_details (Scopus metadata + abstract text from CrossRef).

Development

# install with dev dependencies
uv pip install -e ".[dev]"      # or: pip install -e ".[dev]"

# run the test suite (offline — all HTTP is mocked, no API key needed)
pytest

Tests live in tests/ and mock every external API with httpx.MockTransport, covering result parsing, count clamping, retry/backoff on HTTP 429, quota tracking and error paths.

Tool reference

search_scopus

Param

Type

Default

Description

query

string

—

Scopus query, e.g. TITLE(agile) AND PUBYEAR > 2020

count

int

5

Results to return (max 25)

sort

string

coverDate

coverDate or relevancy

Each result carries issn and e_issn, which feed straight into get_journal_metrics.

get_abstract_details

Param

Type

Description

scopus_id

string

Scopus document ID

get_author_profile

Param

Type

Description

author_name

string

Author's full name, e.g. Amy Edmondson. Returns the top 3 OpenAlex matches — verify by name/affiliation.

get_citing_papers

Forward citations — papers that cite the given document.

Param

Type

Default

Description

scopus_id

string

—

A DOI or OpenAlex work ID (default source), or a Scopus ID

count

int

5

Results to return (max 25)

sort

string

coverDate

coverDate or relevancy (Scopus only)

source

string

openalex

openalex (free, no quota, most-cited first) or scopus

Why OpenAlex is the default: Scopus serves forward citations through the REFEID() search field, which is restricted. On a free key it returns HTTP 400 INVALID_INPUT ("Use of certain field restrictions in the search query is not allowed for this requestor"), so source="scopus" is only useful with an institutional subscription. If you request it anyway, the tool reports that restriction rather than leaking a bare HTTP error.

get_references

Backward citations — papers cited by the given document, most-cited first.

Param

Type

Default

Description

identifier

string

—

DOI, OpenAlex work ID (W…) or Scopus ID

count

int

10

References to return (max 25)

Reference lists come from OpenAlex, falling back to CrossRef when OpenAlex has none. For works with more than 50 references, ranking considers the first 50; total_references always reports the true count.

assess_relevance

Evidence for screening papers against a research context — no verdict, no score.

Param

Type

Description

identifiers

string[]

Up to 25 papers (DOI, OpenAlex ID or Scopus ID)

research_context

string

What you are looking for, e.g. psychological safety in distributed software teams

Returns per paper: title, DOI, year, venue, citation count, abstract, scored topics and keywords, and lexical_overlap (matched_terms, missing_terms, coverage). Identifiers that cannot be resolved are reported under unresolved rather than silently dropped.

Identifiers

get_references and assess_relevance accept a DOI (preferred — free), an OpenAlex work ID, or a Scopus ID. A Scopus ID costs one Scopus call to resolve its DOI first, so pass DOIs when you have them.

get_pdf_link

Param

Type

Description

doi

string

DOI, e.g. 10.1016/j.tourman.2026.105478

get_journal_metrics

Param

Type

Description

issn

string

Journal ISSN, with or without the hyphen, e.g. 0001-8392

Returns the quartile (Q1–Q4) per subject category, plus CiteScore, SJR and SNIP. A journal usually sits in several categories with different quartiles, so subject_areas is a list; best_quartile gives the strongest one, which is what papers normally cite.

The source field says where the numbers came from — scopus from the live Serial Title API, scimago from the local fallback table. The two differ slightly, so it is worth reporting which one you used.

The Serial Title API needs an entitlement many keys lack. When it is unavailable the tool falls back to a Scimago table you place at research_mcp/data/scimago.csv — see that directory's README for how to obtain it. The Scimago data is licensed CC BY-NC.

Scopus query syntax (quick reference)

Field

Example

Title

TITLE(machine learning)

Author

AUTH(edmondson)

Keywords

KEY(psychological safety)

Year

PUBYEAR > 2020, PUBYEAR = 2023

Affiliation

AFFIL(harvard)

Combined

TITLE(agile) AND KEY(teams) AND PUBYEAR > 2019

Full syntax: Scopus Search Tips.

License

MIT — see LICENSE.

Acknowledgements

Built on the open scholarly infrastructure of CrossRef, OpenAlex and Unpaywall, plus the Elsevier Scopus API.

Available Tools

9 tools
assess_relevanceA

Screen one or more papers against a research context. Returns, per paper, the abstract (from OpenAlex — broader coverage than CrossRef), scored topics and keywords, and which of your context's terms do and do not appear. Use it to triage a whole search result set in one call, then judge relevance yourself: the server deliberately returns evidence, not a verdict or score.

ParametersJSON Schema
NameRequiredDescriptionDefault
identifiersYesUp to 25 paper identifiers (DOI, OpenAlex ID or Scopus ID).
research_contextYesWhat you are looking for, e.g. "psychological safety in distributed software teams". Be specific: the term-overlap signal is computed from this text.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the transparency burden. It discloses meaningful behavior: results are per paper, abstracts come from OpenAlex, and the server deliberately returns evidence rather than a verdict or score. It does not mention auth, rate limits, or side effects, but the read-only screening nature is strongly implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: purpose first, then return contents, then usage guidance. Three sentences carry all necessary information without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description needs to explain return values, and it does: abstract, scored topics and keywords, and matched/unmatched context terms. It could be more precise about the exact output structure or scoring, but it is complete enough for triage use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the purpose of identifiers and research_context and ties research_context to term-overlap, but it does not add substantial meaning beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb and resource: 'Screen one or more papers against a research context.' It clearly distinguishes the tool by emphasizing batch triage of a whole search result set and explicitly says it returns evidence, not a verdict, which sets it apart from sibling tools like get_abstract_details or search_scopus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear guidance on when to use it: 'Use it to triage a whole search result set in one call, then judge relevance yourself.' It stops short of explicitly naming alternatives or stating when not to use it, but the intended workflow and division of responsibility are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_abstract_detailsA

Retrieve metadata for a Scopus document (authors, journal, citations) plus the abstract text from CrossRef when available.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopus_idYesThe Scopus document ID.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that abstract text is included 'when available' from CrossRef, indicating potential absence. However, it does not mention other behavioral traits such as authentication requirements, rate limits, error states, or data freshness, which would be valuable given no annotations are provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant text. Every word contributes to understanding the tool's purpose and a key behavioral caveat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers the purpose and an important detail (abstract availability). It could be more complete by mentioning typical output structure or error handling, but it is adequate for basic agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description does not add specific meaning to the scopus_id parameter beyond what the schema already states ('The Scopus document ID'). The tool's overall function is described but no parameter-level detail is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the function: retrieving metadata (authors, journal, citations) and abstract text from CrossRef. It is specific about the resource (Scopus document) and distinguishes from sibling tools like get_author_profile and get_citing_papers by combining multiple data types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining full document details via a scopus_id, but does not provide explicit guidance on when to use this tool over alternatives, nor does it mention when not to use it. Sibling tools are not named or contrasted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_author_profileA

Look up an author's h-index, citation count, paper count, ORCID and affiliations via OpenAlex. Provide the author's full name; returns the top 3 matches to disambiguate.

ParametersJSON Schema
NameRequiredDescriptionDefault
author_nameYesFull name of the author, e.g. "Amy Edmondson".

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It discloses the data source (OpenAlex) and the disambiguation behavior (returns top 3 matches). However, it does not mention error handling, rate limits, authentication, or what happens if no matches are found, leaving gaps in behavioral expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, each serving a clear purpose: the first states the functionality and outputs, the second specifies the input and a key behavior. There is no wasted text; it is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (single parameter, no output schema), the description covers the main aspects: what it returns, how to call it, and a key behavioral trait (disambiguation). It does not detail the output structure or error cases, but these are minor omissions for a low-complexity tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema describes the single parameter with an example. The description adds context by explaining the purpose of the parameter (author's full name) and the effect (returns top 3 matches for disambiguation), enhancing understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool looks up an author's h-index, citation count, paper count, ORCID, and affiliations via OpenAlex. It specifies the input (full name) and output (top 3 matches for disambiguation), distinguishing it from sibling tools that handle abstracts, citations, PDFs, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to provide the author's full name and notes that the top 3 matches are returned for disambiguation. It implies usage when an author's identity needs clarification, but does not explicitly mention when not to use or compare to siblings, though the sibling list provides context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_citing_papersA

Forward citations: papers that CITE a given document, most-cited first. Defaults to OpenAlex (free, no quota, wide coverage, accepts a DOI or OpenAlex ID). source='scopus' uses REFEID(), a restricted field that only works with an institutional Scopus subscription.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNoSort by 'coverDate' or 'relevancy'.coverDate
countNoResults to return (default 5, max 25).
sourceNoWhich database to query. Default 'openalex'; 'scopus' requires an institutional subscription.openalex
scopus_idYesDocument identifier: a DOI or OpenAlex work ID (default OpenAlex source), or a Scopus ID.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the description discloses an important constraint: the 'scopus' source requires an institutional subscription and uses a restricted field (REFEID). This covers a key behavioral caveat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise and well-structured, conveying essential information in three sentences without redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple and the description provides enough context for correct invocation, including source selection, identifier types, and ordering. No output schema is present, but the description sufficiently frames expected results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions. The description adds context about the identifier formats (DOI, OpenAlex ID, Scopus ID), default source, and sort options, enhancing understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns forward citations (papers citing a given document) and specifies ordering (most-cited first). It distinguishes from siblings like get_references (backward citations) and search_scopus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on default source (OpenAlex) and when to use the alternative source ('scopus' requires institutional subscription). Implicitly indicates use case for forward citation lookup, though no explicit comparison to all siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_journal_metricsA

Journal quality metrics for an ISSN: the quartile (Q1-Q4) per subject category, plus CiteScore, SJR and SNIP. Uses the Scopus Serial Title API and falls back to the bundled Scimago table when that is unavailable. Get an ISSN from search_scopus or get_abstract_details.

ParametersJSON Schema
NameRequiredDescriptionDefault
issnYesJournal ISSN, with or without the hyphen, e.g. "0001-8392".

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the primary data source (Scopus Serial Title API) and the automatic fallback to a bundled Scimago table when it is unavailable. It omits auth requirements, rate limits, and latency, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each earning its place: what comes back, how it is sourced, and how to get the input. The payload is front-loaded ahead of the sourcing and prerequisite details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the returned metrics (quartile, CiteScore, SJR, SNIP). Combined with the source/fallback note and the ISSN sourcing hint, an agent has enough to call it correctly for a one-parameter tool; finer details like response shape per category are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter with 100% schema description coverage, so the schema already explains the ISSN format with an example. The description says the input is an ISSN (and implicitly points at sources for it) but adds no format nuance beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific resource (journal quality metrics for an ISSN) and enumerates exactly what comes back — quartile per subject category, CiteScore, SJR, SNIP. It is clearly distinguishable from siblings like search_scopus or get_author_profile. It lacks an explicit verb, but the resource and payload are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides real routing guidance: it tells the agent where to obtain the required ISSN (search_scopus or get_abstract_details), which is the main precondition for calling it. It stops short of stating when NOT to use the tool or what to do if no metric exists for an ISSN.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quota_statusA

Report the Scopus API rate-limit (weekly quota) from the most recent response headers. Returns a note if no Scopus call has been made yet.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses that the tool reads from response headers and returns a note if no call has been made, indicating a safe, read-only operation with no destructive effects. Behavioral traits are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and contains no redundant information. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and a simple purpose, the description sufficiently covers what the tool does, how it obtains data, and an edge case. It is complete for a status-checking tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no parameters (baseline 4). Description adds meaning beyond schema by explaining the data source (recent response headers) and an edge case (no call made yet), which is valuable context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports the Scopus API rate-limit (weekly quota) from recent response headers, with a specific verb 'Report' and resource. It is distinct from sibling tools which deal with abstracts, profiles, papers, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking quota after Scopus calls, and mentions a note if no call has been made, but does not explicitly state when not to use or provide alternatives. The context is clear but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_referencesA

Backward citations: the works a given paper CITES (its reference list), via OpenAlex with a CrossRef fallback. Free and does not consume Scopus quota — Scopus itself cannot serve reference lists without an institutional subscription. Returns the most-cited references first.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNoReferences to return (default 10, max 25).
identifierYesPaper identifier: a DOI (preferred — free, no Scopus quota), an OpenAlex work ID (e.g. "W2156435103"), or a Scopus ID (costs one Scopus call to resolve the DOI).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It mentions ordering (most-cited first) and quota behavior, but does not address error handling, rate limits, or what happens if the identifier is invalid. This is partial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, with two clear sentences. It avoids unnecessary detail and focuses on essential information, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It communicates the core function and key characteristics (free, fallback, ordering). Since there is no output schema, the lack of return format details is acceptable. However, it could have briefly differentiated itself from forward citations (get_citing_papers) for full context, though 'backward citations' already implies this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes both parameters (identifier types, count default and max). The description adds no new semantic information beyond what is in the schema, so it provides no extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns backward citations (the reference list) for a paper, with a fallback mechanism. This unambiguously defines the tool's primary purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It notes that the tool is free and does not consume Scopus quota, which implies when to prefer it (to avoid quota usage). However, it does not explicitly name alternatives like get_citing_papers or search_scopus for comparison, leaving some inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_scopusA

Search for documents in Scopus by query string. Returns title, DOI, Scopus ID, citation count and journal for each match.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNoSort by 'coverDate' or 'relevancy'.coverDate
countNoResults to return (default 5, max 25).
queryYesScopus query, e.g. "TITLE(agile) AND PUBYEAR > 2020".

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It states it returns specific fields, implying a read-only operation. However, it does not mention authentication needs, rate limits, or that results are limited by the 'count' parameter (max 25). The description is adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the tool's purpose and output. It is front-loaded and contains no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description covers the main inputs and outputs. However, it omits details about response format, pagination (though count is in schema), and potential error states. Still, it is sufficiently complete for a straightforward search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already describes all three parameters (query, sort, count) with details. The description adds no additional context beyond what the schema provides, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for documents') and the resource ('in Scopus'), and explicitly lists the returned fields (title, DOI, Scopus ID, citation count, journal). This distinguishes it from sibling tools like get_abstract_details or get_author_profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where sibling tools (e.g., get_citing_papers) would be more appropriate, nor does it specify constraints like requiring a valid subscription.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.6.0
    • Addedget_journal_metrics
  2. 3 tool updatesv0.5.1
    • Addedassess_relevance
    • Changedget_citing_papers2 fields changed
      • changedInput schema / properties / scopus_id / description
        Previous value: -"Scopus ID of the document."New value: +"Document identifier: a DOI or OpenAlex work ID (default OpenAlex source), or a Scopus ID."
      • addedInput schema / properties / source
        Added value: +{
+  "default": "openalex",
+  "description": "Which database to query. Default 'openalex'; 'scopus' requires an institutional subscription.",
+  "enum": [
+    "openalex",
+    "scopus"
+  ],
+  "type": "string"
+}
    • Addedget_references
  3. 6 tool updatesv0.4.0
    • First observedget_abstract_details
    • First observedget_author_profile
    • First observedget_citing_papers
    • First observedget_pdf_link
    • First observedget_quota_status
    • First observedsearch_scopus
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 9 tools

Disambiguation4/5

Purposes are largely distinct: search vs. citation graph (backward/forward) vs. author vs. journal metrics vs. PDF lookup are cleanly separated, and get_references vs. get_citing_papers are explicitly contrasted. The only mild overlap is that both assess_relevance and get_abstract_details return abstract text, which could confuse an agent wanting just an abstract.

Naming Consistency5/5

Consistent snake_case verb_noun pattern throughout (get_abstract_details, get_author_profile, get_journal_metrics, get_citing_papers, etc.). The two non-'get' verbs (search_scopus, assess_relevance) still follow the same verb_noun convention and read naturally.

Tool Count5/5

Nine tools is well-scoped for a literature-research workflow, with no redundant or trivial entries. Each tool (search, metadata, citations, author, journal metrics, PDF, relevance, quota) earns its place.

Completeness4/5

Covers the core research-discovery lifecycle: search, metadata/abstracts, backward and forward citations, author profiles, journal quality, OA PDF, and relevance triage, plus a quota utility. Minor gaps exist around saving/exporting results or citation formatting, but nothing that blocks typical workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Academic Paper MCP HTTP/SSE

    pastchais
    A
    license
    Not graded
    quality
    D
    maintenance
    A MCP server for academic literature retrieval, aggregating multiple data sources like arXiv, Crossref, OpenAlex, PubMed, and Semantic Scholar to provide search, details, citations, trends, and recommendations.
    4
    MIT

  • classScopusMCP

    TaehongKim
    F
    license
    A
    quality
    D
    maintenance
    An MCP server that integrates Scopus, Crossref, and PubMed APIs to search academic papers and fetch abstracts, usable with any MCP-compatible AI client.
    2
    -