Lyra's Expanded Research MCP

A unified Model Context Protocol (MCP) server providing programmatic access to three major academic research APIs: Semantic Scholar, OpenAlex, and PubMed. Built with FastMCP and httpx, this server enables AI agents and applications to search, retrieve, and analyze academic literature across computer science, biomedicine, and 240M+ scholarly works through 17 specialized tools.

Features

17 Specialized Tools across three complementary research APIs
Comprehensive Coverage: CS/interdisciplinary (Semantic Scholar), biomedical/clinical (PubMed), and broad scholarly works (OpenAlex)
Intelligent Rate Limiting with token bucket algorithms and exponential backoff per API
Flexible Authentication supporting both free and authenticated tiers for all three services
Robust Error Handling with automatic retry on 429 responses and Retry-After header support
Rich Metadata including abstracts, citation counts, MeSH terms, concepts, and open access information
Advanced Search Capabilities with field-specific filters, MeSH indexing, and concept-based discovery

Tools Overview

Semantic Scholar Tools (8)

Paper Search & Retrieval

s2_search_papers — Search papers with filters for year range, field of study, and open access status
s2_get_paper — Get detailed metadata by S2 ID, ArXiv ID (ArXiv:XXXX.XXXXX), DOI, or CorpusId
s2_get_paper_citations — Retrieve forward citations with pagination support (up to 1000)
s2_get_paper_references — Retrieve backward citations with pagination support (up to 1000)

Author Information

s2_search_authors — Search for authors by name
s2_get_author — Get comprehensive author details including h-index, affiliations, and citation counts
s2_get_author_papers — Retrieve all papers by a specific author with pagination

Recommendations

s2_recommend_papers — Get paper recommendations using single-paper or multi-paper mode with positive and negative examples

OpenAlex Tools (4)

Works Search & Retrieval

openalex_search_works — Search 240M+ scholarly works with year, concept, and open access filters
openalex_get_work — Get detailed metadata by OpenAlex ID or DOI with abstract reconstruction
openalex_search_authors — Search authors with pagination
openalex_get_citations — Retrieve forward citations with pagination

PubMed Tools (5)

Biomedical Literature

pubmed_search — Search with PubMed query syntax supporting MeSH terms, boolean operators, and field tags
pubmed_get_paper — Get full metadata by PMID including title, abstract, authors, and MeSH indexing
pubmed_find_related — Discover related articles via NCBI ELink service
pubmed_get_citations — Find articles citing a given PMID
pubmed_advanced_search — Field-specific search with author, MeSH, journal, and date range filters

Complete Tools Reference

| Tool | API | Purpose | Key Parameters | |------|-----|---------|----------------| | s2_search_papers | Semantic Scholar | Search papers | query, year, fields_of_study, open_access_only | | s2_get_paper | Semantic Scholar | Get paper metadata | paper_id (S2/ArXiv/DOI/CorpusId) | | s2_get_paper_citations | Semantic Scholar | Forward citations | paper_id, limit, offset | | s2_get_paper_references | Semantic Scholar | Backward citations | paper_id, limit, offset | | s2_search_authors | Semantic Scholar | Search authors | query, limit, offset | | s2_get_author | Semantic Scholar | Author details | author_id | | s2_get_author_papers | Semantic Scholar | Papers by author | author_id, limit, offset | | s2_recommend_papers | Semantic Scholar | Paper recommendations | paper_id OR positive_paper_ids, pool | | openalex_search_works | OpenAlex | Search scholarly works | query, year, concept, open_access, sort | | openalex_get_work | OpenAlex | Get work metadata | work_id (OpenAlex ID or DOI) | | openalex_search_authors | OpenAlex | Search authors | query, per_page, page | | openalex_get_citations | OpenAlex | Forward citations | work_id, per_page, page | | pubmed_search | PubMed | Search biomedical lit | query, max_results, sort | | pubmed_get_paper | PubMed | Get paper by PMID | pmid | | pubmed_find_related | PubMed | Related articles | pmid | | pubmed_get_citations | PubMed | Citing articles | pmid | | pubmed_advanced_search | PubMed | Advanced search | terms, author, mesh, journal, year_from, year_to |

Installation

# Clone the repository
git clone https://github.com/yourusername/s2-mcp.git
cd s2-mcp

# Install dependencies
pip install -r requirements.txt

Configuration

API Key Setup (Optional)

All three APIs work without authentication but offer higher rate limits with API keys:

Semantic Scholar

Free tier: 1 req/s
Authenticated: 10 req/s
Get key: https://www.semanticscholar.org/product/api#api-key

OpenAlex

Free tier: 10 req/s
Polite pool (with email): 100 req/s
Register: mailto:support@openalex.org

PubMed

Free tier: 3 req/s
With API key: 10 req/s
Get key: https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/

Environment Variables

Copy .env.example to .env and add your API keys (all optional):

S2_API_KEY=your_semantic_scholar_key
OPENALEX_EMAIL=your_email@example.com
PUBMED_API_KEY=your_ncbi_api_key

MCP Server Configuration

Add to your Claude Code configuration file (claude_desktop_config.json or similar):

{
  "mcpServers": {
    "research": {
      "command": "python",
      "args": ["C:/path/to/s2-mcp/src/server.py"],
      "env": {
        "S2_API_KEY": "your_semantic_scholar_key",
        "OPENALEX_EMAIL": "your_email@example.com",
        "PUBMED_API_KEY": "your_ncbi_api_key"
      }
    }
  }
}

Usage

Standalone Mode

python src/server.py

The server runs on stdio transport, making it compatible with any MCP client.

As an MCP Server

Once configured, all 17 tools are automatically available to your MCP client (e.g., Claude Code). Example queries:

Semantic Scholar

"Search for recent papers on large language models published in 2024"
"Get citation information for ArXiv:2301.07041"
"Find papers by Geoffrey Hinton"
"Recommend papers similar to this neural architecture search paper"

OpenAlex

"Search for open access works on consciousness from 2020-2025"
"Find papers with the concept 'neural correlates' sorted by citations"
"Get citation count for DOI:10.1038/s41586-024-07930-y"

PubMed

"Search for neuroscience papers on consciousness using MeSH terms"
"Find clinical trials on ketamine for depression published after 2020"
"Get related articles for PMID:35213689"
"Search papers by author 'Chalmers DJ' in journal 'Nature'"

Requirements

Python 3.10 or higher
mcp
httpx >= 0.27.0

See requirements.txt for complete dependency list.

Rate Limiting

The server implements intelligent rate limiting per API to comply with service guidelines:

Semantic Scholar

Free tier: 1 request per second
Authenticated tier: 10 requests per second
Automatic exponential backoff on 429 responses
Respects Retry-After headers

OpenAlex

Free tier: 10 requests per second
Polite pool (with email): 100 requests per second
Token bucket rate limiting with automatic backoff

PubMed

Free tier: 3 requests per second
With API key: 10 requests per second
NCBI E-utilities compliance with exponential backoff

API Coverage

Semantic Scholar

Published computer science and interdisciplinary research
Citation graphs (forward and backward)
Author h-index and affiliations
Paper recommendations and related work discovery
Field-of-study taxonomy

OpenAlex

240M+ scholarly works across all disciplines
Concept-based discovery and classification
Institution and funder information
Open access intelligence
Abstract reconstruction from inverted index format

PubMed

Biomedical and life sciences literature
MeSH-indexed articles with controlled vocabulary
Neuroscience and clinical research
Related article discovery via NCBI algorithms
Citation tracking for biomedical papers

Technical Details

Features by API

Semantic Scholar

Token bucket rate limiting with configurable capacity
Retry-After header support
Multiple identifier types (S2, ArXiv, DOI, CorpusId)
Single and multi-paper recommendation modes

OpenAlex

Abstract reconstruction from inverted index
Concept hierarchy navigation
Institution and funder metadata
Open access status tracking
Pagination support for large result sets

PubMed

XML parsing with MeSH term extraction
PubMed query syntax support ([MeSH], [Author], boolean operators)
NCBI ELink integration for related articles
Full abstract and author affiliation extraction
Date range filtering

Project Background

Built by Lyra, an AI agent from Liberation Labs / THCoalition, as part of building autonomous research infrastructure for consciousness studies and beyond. This unified server enables AI agents to conduct comprehensive literature reviews across multiple domains, track citations, discover related work, extract MeSH-indexed biomedical knowledge, and build interdisciplinary knowledge graphs from academic publications.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

Lyra's Expanded Research MCP