MCP Badge License: MIT Python 3.11+ MCP

Scopus MCP Server

Connects any MCP-compatible AI agent to the Elsevier Scopus academic database — search 100+ million scholarly records, retrieve full abstracts, analyze author impact, and track citation trends.

Works with: Claude Desktop · Claude Code · Cursor · VS Code Copilot · Windsurf · Zed · Continue.dev · any MCP client

---

Quickstart (2 minutes)

1. Get your Scopus API key (free) at dev.elsevier.com → Register → Create API Key

2. Install and run — pick one method:

# Option A: uvx (recommended — no environment setup needed)
uvx scopus-mcp

# Option B: pip
pip install scopus-mcp
scopus-mcp

3. Add to your AI client — see the Configuration section below.

---

Prerequisites

Python 3.11+

python --version   # needs 3.11 or higher
# Install if missing: https://python.org/downloads

uv (recommended)

# Windows
winget install astral-sh.uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

---

Installation

Option A — uvx (zero configuration)

# Install and run in a single command
uvx scopus-mcp

# Upgrade later
uv tool upgrade scopus-mcp

Option B — pip

pip install scopus-mcp

# Verify installation
scopus-mcp --help

Option C — From source (development)

git clone https://github.com/JOSETRA44/scopus-mcp.git
cd scopus-mcp
uv sync                    # installs all dependencies
cp .env.example .env       # edit .env with your API key
uv run scopus-mcp          # run directly from source

---

Terminal CLI

Besides running as an MCP server, scopus-mcp also installs three equivalent commands — scopus-mcp, scopus, and the short alias scps — as a standalone command-line tool for one-off lookups, testing your API key, or scripting, no MCP client required.

# Install globally as a uv tool (adds scopus / scps / scopus-mcp to PATH)
uv tool install --editable /path/to/scopus-mcp

scopus --help                 # list all subcommands
scopus check                  # validate your API key live against each endpoint
scopus search 'TITLE-ABS-KEY("machine learning")' --count 5
scps abstract 85180904906 --type scopus_id
scopus author 7401234567
scopus search-authors "AUTHLASTNAME(Smith)"
scopus search-affiliations "AFFIL(MIT)"
scopus citation-count --doi 10.1016/j.cell.2023.01.001
scopus citations 85180904906 --start-year 2020 --end-year 2024

Add --json to any subcommand for raw structured output (useful for piping into jq or scripts).

Running any of the three commands with no subcommand starts the MCP stdio server instead — the mode MCP clients (Claude Desktop, Claude Code, etc.) use. It will sit waiting for input on stdin; that's expected, not a hang.

Subcommand	Equivalent MCP tool
search <query>	scopus_search
abstract <id> --type ...	scopus_get_abstract
author <author_id>	scopus_get_author
search-authors <query>	scopus_search_authors
search-affiliations <query>	scopus_search_affiliations
citation-count --scopus-id/--doi	scopus_get_citation_count
citations <scopus_id>	scopus_get_citations_overview
check	(CLI-only) diagnostic — live-checks your key against every endpoint

---

Environment Variables

Variable	Required	Default	Description
SCOPUS_API_KEY	Yes	—	Your Elsevier API key
SCOPUS_INST_TOKEN	No	—	Institutional token (for off-campus / full-text access)
SCOPUS_CACHE_TTL	No	300	Response cache duration in seconds (0 = disabled)
SCOPUS_MAX_RETRIES	No	3	Retries on rate-limit errors (HTTP 429)
LOG_LEVEL	No	INFO	Verbosity: DEBUG · INFO · WARNING · ERROR

Using a .env file? Copy .env.example → .env and fill in your key. Never commit it.

---

Configuration by Client

Replace YOUR_API_KEY_HERE with your actual Elsevier API key in every config block below.

Claude Desktop

Config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scopus": {
      "command": "uvx",
      "args": ["scopus-mcp"],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop after saving. A hammer icon (🔨) in the input bar confirms tools are loaded.

Claude Code (CLI)

Add to your project's .mcp.json (or .antigravity.json):

{
  "mcpServers": {
    "scopus": {
      "command": "uvx",
      "args": ["scopus-mcp"],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

From source (local development):

{
  "mcpServers": {
    "scopus": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/scopus-mcp",
        "run", "scopus-mcp"
      ],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Run /mcp in the Claude Code prompt to verify — you should see scopus with 7 tools.

Cursor

Global config: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json (Windows)

{
  "mcpServers": {
    "scopus": {
      "command": "uvx",
      "args": ["scopus-mcp"],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

VS Code + GitHub Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "scopus": {
      "type": "stdio",
      "command": "uvx",
      "args": ["scopus-mcp"],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Windsurf

Config: %APPDATA%\Codeium\windsurf\mcp_config.json (Windows)

{
  "mcpServers": {
    "scopus": {
      "command": "uvx",
      "args": ["scopus-mcp"],
      "env": {
        "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "scopus": {
      "command": {
        "path": "uvx",
        "args": ["scopus-mcp"],
        "env": {
          "SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

Continue.dev

Edit .continue/config.yaml:

mcpServers:
  - name: scopus
    command: uvx
    args:
      - scopus-mcp
    env:
      SCOPUS_API_KEY: "YOUR_API_KEY_HERE"

Generic stdio (any MCP client)

command:  uvx
args:     ["scopus-mcp"]
env:      SCOPUS_API_KEY=YOUR_API_KEY_HERE

---

Automated Setup Script

# Interactive setup (auto-detects installed clients)
python setup_mcp.py

# Non-interactive
python setup_mcp.py --key YOUR_API_KEY_HERE --yes

# Dry-run preview
python setup_mcp.py --key YOUR_API_KEY_HERE --dry-run --yes

---

Available Tools (7)

Tool	Description
scopus_search	Search papers with Boolean queries — TITLE-ABS-KEY, AUTH, AFFIL, PUBYEAR, DOCTYPE…
scopus_get_abstract	Full paper record by Scopus ID, DOI, EID, or PubMed ID
scopus_get_author	Researcher profile: h-index, total citations, document count, affiliation, ORCID
scopus_search_authors	Find researchers by name, ORCID, or institution
scopus_search_affiliations	Find institution records by name or country
scopus_get_citation_count	Quick citation count by Scopus ID or DOI
scopus_get_citations_overview	Year-by-year citation timeline for a paper

---

Available Prompts (3)

Prompts are reusable research workflows that generate structured query strategies.

Prompt	Arguments	Description
systematic_literature_review	topic, population, intervention, outcome, start_year	Generates a PICO-framed SLR search strategy with Boolean queries and PRISMA flow template
author_impact_analysis	author_name, institution	Step-by-step plan to evaluate a researcher's h-index, citation trends, and collaboration network
research_trend_query	topic, field_code, compare_topic	Decade-by-decade publication trend queries with document type breakdown and OA analysis

---

Available Resources (3)

Resources are reference documents agents can read at any time.

Resource URI	Contents
scopus://search-syntax	Complete Boolean query reference — field codes, operators, wildcards, examples
scopus://subject-areas	All SUBJAREA() discipline codes organized by field
scopus://api-reference	Tool quota costs, identifier formats, and recommended workflow patterns

---

Example Queries

# Find recent papers on a topic
TITLE-ABS-KEY("machine learning" AND cancer) AND PUBYEAR > 2020

# Reviews only
TITLE-ABS-KEY("federated learning") AND DOCTYPE(re)

# By author ID
AU-ID(7401234567) AND SUBJAREA(COMP)

# From a specific institution
AF-ID(60022195) AND TITLE-ABS-KEY("robotics")

# Open access papers in a specific journal
SRCTITLE("Nature Medicine") AND OPENACCESS(1) AND PUBYEAR > 2022

# Cross-disciplinary topic
TITLE-ABS-KEY("climate change") AND (SUBJAREA(ECON) OR SUBJAREA(ENVI))

---

Rate Limits

The server tracks rate limits from response headers and sleeps automatically before making calls when quota is exhausted.

Endpoint	Weekly Quota
Scopus Search	20,000
Abstract Retrieval	5,000
Author Retrieval	5,000
Citation Count	50,000
Citations Overview	5,000

Tip: Use scopus_get_citation_count (50K quota) for bulk citation checks. Reserve scopus_get_abstract (5K quota) for the papers you actually need in detail.

---

Verify It's Working

# Fastest check: validates your API key live against every endpoint
scopus check

# Interactive browser UI (recommended for MCP-specific debugging)
npx @modelcontextprotocol/inspector uvx scopus-mcp

# Quick smoke test (server starts and exits cleanly)
echo "" | SCOPUS_API_KEY=your_key uvx scopus-mcp

# Unit tests (from source)
uv sync --group dev
uv run pytest tests/ -v
# Expected: 19 passed

---

Troubleshooting

command not found: uvx Install uv: https://docs.astral.sh/uv/getting-started/installation/

Configuration error: Missing required environment variable: SCOPUS_API_KEY Make sure your config's "env" block has "SCOPUS_API_KEY": "your_actual_key" — not a placeholder.

Tools fail with HTTP 401 API key is invalid or expired. Regenerate at dev.elsevier.com.

Tools fail with HTTP 403 Your key may lack Scopus access. An institutional subscription is required for most endpoints. Ask your librarian about SCOPUS_INST_TOKEN.

First run is slow uv downloads and caches the package on first run. Subsequent starts take ~0.2s.

Tools appear but return empty results Try broadening your query: replace TITLE(...) with TITLE-ABS-KEY(...) or remove PUBYEAR constraints.

---

Project Structure

scopus-mcp/
├── src/scopus_mcp/
│   ├── server.py        # Entry point — dispatches to CLI or FastMCP stdio server
│   ├── cli.py           # Terminal CLI (scopus / scps): subcommands + check diagnostic
│   ├── config.py        # Env var configuration (pydantic-settings)
│   ├── client.py        # Async HTTP client + TTL cache + rate limiter
│   ├── exceptions.py    # Error hierarchy
│   ├── formatters.py    # Raw Scopus JSON → clean AI-friendly dicts
│   ├── tools/           # 7 MCP tools (search, abstract, author, citations)
│   ├── prompts/         # 3 MCP prompts (SLR, author analysis, trend query)
│   └── resources/       # 3 MCP resources (syntax, subject areas, API reference)
├── scopus-researcher/   # Agent skill (npx skills add JOSETRA44/scopus-mcp@scopus-researcher)
│   ├── SKILL.md
│   └── references/
├── tests/               # Unit tests (19 cases, no network required)
├── setup_mcp.py         # Automated config installer for all clients
├── .env.example         # Environment variable template
└── pyproject.toml       # Package definition

---

License

MIT — © 2026 JOSETRA44