Lyra'S Expanded Research

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:[email protected]

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
[email protected]
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": "[email protected]",
        "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.

Links

• Semantic Scholar API Documentation
• OpenAlex API Documentation
• PubMed E-utilities Documentation
• Model Context Protocol Specification
• FastMCP Framework