io.github.mlintangmz2765/scholar

Scholar MCP Server

A Model Context Protocol (MCP) server providing structured access to scientific literature databases. It serves as a unified interface for Scopus, OpenAlex, Semantic Scholar, and Unpaywall, enabling AI agents to perform systematic paper discovery, author disambiguation, citation lineage tracking, and multimodal Content extraction.

Core Capabilities

• Unified Literature Search
  • Semantic Scholar Integration — High-relevance search and detailed metadata, including AI-generated TLDRs (requires API key).
  • Scopus Integration — Targeted metadata retrieval via advanced Boolean syntax (requires API key).
  • OpenAlex Integration — Broad search across 250M+ works with abstract reconstruction.
  • Unpaywall Resolution — DOI-to-PDF cross-referencing across global Open Access repositories.
  • Sci-Hub Fallback (⚠️ Use with Caution) — Automatic mirror resolution and parsing for paywall bypassing.
• Book Search & Extraction
  • Google Books & Open Library — Integrated search for book metadata, editions, and descriptions without API keys.
  • Library Genesis (Libgen) — Search and extract full text from books directly using PyMuPDF. Features smart caching and token-saving strategies (TOC reading, targeted keyword searching, and page range extraction).
• Author Identification & Metrics
  • Instant author disambiguation and ID resolution via OpenAlex autocomplete.
  • Comprehensive profiles: H-index, i10-index, institutional affiliation history, and ORCID linkage.
  • Precision metrics from Elsevier (Scopus) for verified publication counts.
• Citation Lineage Tracking
  • Map research evolution through forward citations (citing works) and backward references (cited works).
• Structured & Multimodal Extraction
  • Text Extraction — Layout-aware parsing of OA PDFs using PyMuPDF.
  • Vision Rendering — Page-by-page PNG rendering for LLM-based analysis of charts, tables, and equations.
  • HTML Fallbacks — Extraction from web-based research resources via BeautifulSoup.
• Topic Mapping & Field Analysis
  • Concepts and domain hierarchy discovery to map research landscapes.
  • Batch metadata retrieval for high-throughput literature processing (up to 50 DOIs/request).
• Access Management & Fallbacks
  • Automated detection of closed-access content with human-in-the-loop instructions for manual uploads.

Architecture

graph TD
    A[LLM Agent] -->|MCP Protocol| B(Scholar MCP Server)
    B --> C{Database Router}
    C -->|Primary| D[Scopus API]
    C -->|Fallback| E[OpenAlex API]
    C -->|DOI Resolver| F[Unpaywall API]
    C -->|Citations| P[CrossRef API]
    
    D --> G{Access Check}
    E --> G
    F --> G
    P --> G
    
    G -->|Open Access| H[PDF Buffer Download]
    G -->|Closed Access| I[Human-in-the-Loop Prompt]
    H --> J[PyMuPDF Text Extractor]
    H --> K[PyMuPDF Vision Renderer]
    J --> L[Return Context to LLM]
    K --> L
    I --> L
    B --> M{Author Router}
    M -->|Profile| N[OpenAlex Authors API]
    M -->|Metrics| O[Scopus Author API]
    N --> L
    O --> L

Installation

Quick Start (via PyPI)

The fastest way to use the server is directly via PyPI:

pip install scholar-academic-mcp

Manual Setup (for Development)

# Clone the repository
git clone https://github.com/mlintangmz2765/Scholar-MCP.git
cd Scholar-MCP

# Setup virtual environment
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate # Unix

# Install in editable mode
pip install -e .

Environment Variables

Configuration

Claude Desktop / Cursor

Add the following to your configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "scholar-academic-mcp": {
      "command": "scholar-academic-mcp",
      "env": {
        "SCOPUS_API_KEY": "your_scopus_api_key",
        "S2_API_KEY": "your_s2_api_key",
        "SCIHUB_MIRRORS": "https://sci-hub.ru,https://sci-hub.st",
        "LIBGEN_MIRRORS": "https://libgen.la,http://libgen.li",
        "SCOPUS_INST_TOKEN": "your_optional_inst_token",
        "CONTACT_EMAIL": "your_email@domain.com"
      }
    }
  }
}

Quick Start & Examples

Once configured, your AI agent can perform complex research workflows. Below are representative examples of tool inputs and structured outputs.

1. Literature Discovery (Scopus)

Prompt: "Find recent papers about 'Transformer architectures' published after 2022 using Scopus."

Tool Call: search_papers_tool(query="TITLE-ABS-KEY(Transformer architectures) AND PUBYEAR > 2022", limit=3)

Output:

Found 3 papers via Scopus:
- [SCOPUS_ID:85184...] Attention is All You Need? A Survey of Transformer Variants
  Authors: Smith, J., Doe, A.
  Date: 2024-01-15 | DOI: 10.1016/j.artint.2023.104012

2. Multimodal Content Analysis

Prompt: "I need to see the diagram for the neural network architecture on page 3 of this URL."

Tool Call: get_full_text_visual_tool(url="https://arxiv.org/pdf/1706.03762.pdf", max_pages=3)

Output:

• [Text] "Successfully rendered 3 pages visually..."
• [Image] (PNG data of page 1)
• [Image] (PNG data of page 2)
• [Image] (PNG data of page 3 - containing the architecture diagram)

3. Research Topic Mapping

Prompt: "Help me understand the subfields and domains related to 'Generative AI'."

Tool Call: search_topics_tool(query="Generative AI")

Output:

Found 1 topics for 'Generative AI':
- Artificial Intelligence
  Hierarchy: Computer Science → Artificial Intelligence → Machine Learning
  Works: 12,450 | Citations: 450,210
  Description: A field of computer science that focuses on creating systems capable of generating...

Tools

The server registers 23 tools across 7 categories:

Paper Discovery

Book Discovery & Extraction

Author Analytics

Citation Tracking

Full-Text & PDF

Citation & Writing

Open Access Resolution

Topic Mapping & Batch Analysis

Technical Design & Reliability

Scholar MCP is engineered for precision and fault tolerance in high-stakes research environments, utilizing several layers of protection to ensure data integrity:

• Strict Data Contracts (Pydantic)
  • All upstream API responses are validated against Pydantic models before being returned to the agent.
  • Ensures a predictable, type-safe interface even if upstream database schemas change.
• Fault-Tolerant Networking (Tenacity)
  • Integrated Exponential Backoff using tenacity for transient HTTP errors (429, 5xx).
  • Configurable rate-limit awareness for Elsevier and OpenAlex "polite pool" routing.
• Resource Safety & Concurrency
  • Context-Managed Extractors: Automatic cleanup of PDF buffers and file descriptors.
  • Isolated Concurrency: Batch operations utilize asyncio.gather with localized exception handling to prevent session-wide failures.
• System Observability
  • Structured standard-error (stderr) logging provides execution visibility during the tool lifecycle without interfering with the MCP JSON-RPC protocol.
• Automated Verification
  • Comprehensive test suite leveraging respx for deterministic API mocking, ensuring 100% coverage of edge cases without network externalites.

Project Structure

Scholar-MCP/
├── .github/workflows/ # GitHub Actions (CI & Releases)
├── scripts/           # Automation & Validation scripts
├── tests/             # Pytest suite (respx mocked)
├── server.py          # FastMCP tool entry point
├── api.py             # API Clients (Scopus, OpenAlex, Unpaywall, CrossRef)
├── extractor.py       # PDF/HTML Extraction & Rendering
├── models.py          # Pydantic Data Validation
├── server.json        # MCP Registry Manifest
├── pyproject.toml     # Python packaging configuration
├── requirements.txt   # Dependencies
├── VERSION            # Version tracking (v1.0.0)
├── LICENSE            # MIT License
├── README.md          # Documentation
├── .env.example       # Template for API keys
└── .gitignore         # Git exclusion rules

Troubleshooting

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Commit your changes (git commit -m 'feat: add new capability').
4. Push to the branch (git push origin feature/my-feature).
5. Open a Pull Request.

Please ensure all code follows PEP 8 conventions.

License

MIT License. See LICENSE for details.

Disclaimer: Automated querying of publisher APIs must comply with the respective Terms of Service of Elsevier, OpenAlex, and Unpaywall. Do not distribute API keys. Adhere to all applicable rate limits.

mcp-name: io.github.mlintangmz2765/scholar