mcsci-hub

An MCP server that gives LLMs access to academic literature. Search papers, retrieve metadata, download PDFs, traverse citation graphs, and generate BibTeX -- all through a unified interface backed by four academic data sources.

Built with FastMCP.

search "CRISPR delivery" --> get_paper(doi) --> fetch_pdf(doi) --> [mcp-pdf] --> analyze

How It Works

mcsci-hub aggregates data from multiple academic APIs in parallel, merging results into a single coherent response:

The strategy: always try open access first. Sci-Hub is a last resort. When any source fails, the others still return what they can (graceful degradation).

Tools

Resources

Prompts

Composability with mcp-pdf

fetch_pdf saves PDFs locally and returns the file path. Tool responses and prompts guide the calling LLM to use mcp-pdf for full-text extraction, creating the pipeline:

search --> fetch --> parse --> analyze

Install mcp-pdf alongside mcsci-hub to unlock the full workflow.

Installation

Requires Python 3.11+.

# Clone and install
git clone git@git.supported.systems:MCP/mcsci-hub.git
cd mcsci-hub
uv sync

# Copy and edit environment config
cp .env.example .env

Add to Claude Code

Two transport modes are supported. Pick HTTP if you run multiple Claude sessions on the same machine, it gives you one shared server across every session (shared cache, shared rate-limit budgets, no per-session subprocess cost). Stdio is simpler and fine for a single user, single session.

HTTP transport (recommended for multi-session use):

# Start the HTTP server in the background (systemd user service, see below)
mcsci-hub --http

# Register with Claude Code (user scope, available in every project)
claude mcp add -s user -t http mcsci-hub http://127.0.0.1:8788/mcp/

Stdio transport (one subprocess per Claude session):

# Local development
claude mcp add mcsci-hub -- uv run --directory /path/to/mcsci-hub mcsci-hub

# From PyPI
claude mcp add mcsci-hub -- uvx mcsci-hub

Running as a persistent HTTP server (systemd user service)

For the HTTP transport, run mcsci-hub --http under systemd so it starts on login and restarts on failure. Drop this at ~/.config/systemd/user/mcsci-hub.service:

[Unit]
Description=mcsci-hub FastMCP server (HTTP transport)
After=network.target

[Service]
Type=simple
ExecStart=/path/to/mcsci-hub/.venv/bin/mcsci-hub --http --host 127.0.0.1 --port 8788
WorkingDirectory=/path/to/mcsci-hub
Restart=on-failure
RestartSec=5s

# Optional polite-pool / API key env (uncomment to set)
# Environment=CROSSREF_MAILTO=you@example.com
# Environment=OPENALEX_MAILTO=you@example.com
# Environment=S2_API_KEY=your-key

[Install]
WantedBy=default.target

Enable with systemctl --user daemon-reload && systemctl --user enable --now mcsci-hub.service. Logs land in the user journal (journalctl --user -u mcsci-hub -f). The server binds loopback-only by default, so no auth is needed for local use. If you expose it beyond loopback, put it behind a reverse proxy that enforces auth.

Run standalone

uv run mcsci-hub           # stdio (one subprocess, inherits parent's stdio)
uv run mcsci-hub --http    # HTTP on 127.0.0.1:8788
uv run mcsci-hub --http --port 9000 --host 0.0.0.0   # bind all interfaces

Configuration

All settings are managed via environment variables (loaded from .env by pydantic-settings).

See .env.example for a ready-to-use template.

Data Source Strategy

Each field in the aggregated response has a primary and fallback source:

All sources are queried in parallel via asyncio.gather with return_exceptions=True -- a slow or failing source never blocks the others.

Project Structure

src/mcsci_hub/
  server.py                  # FastMCP app, lifespan, resources, prompts
  config.py                  # pydantic-settings env config
  cache.py                   # TTL-aware LRU cache
  models.py                  # Pydantic response models
  clients/
    crossref.py              # CrossRef API (polite pool, rate limited)
    openalex.py              # OpenAlex API (abstracts, OA URLs)
    semantic_scholar.py      # S2 API (citations, BibTeX)
    scihub.py                # Sci-Hub scraper (mirror rotation, retry)
  tools/
    search.py                # search_papers
    paper.py                 # get_paper + aggregate_paper()
    pdf.py                   # fetch_pdf
    citations.py             # get_citations, get_references
    bibtex.py                # get_bibtex

Development

# Install with dev dependencies
uv sync

# Run tests (55 tests, all mocked with respx + FastMCP in-process transport)
uv run pytest -v

# Run tests with coverage
uv run pytest -v --cov=mcsci_hub

# Lint
uv run ruff check src/ tests/

License

MIT