mcp server

scopus-mcp

permite a agentes a realizar búsquedas en scopus, investigaciones, papers

JOSETRA44/scopus-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "josetra44-scopus-mcp": {
      "command": "uvx",
      "args": [
        "scopus-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

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