scvi-tools MCP

An MCP (Model Context Protocol) server that gives LLMs structured access to scvi-tools knowledge: model documentation, tutorials, API reference, workflow templates, pretrained Hugging Face Hub models, and community knowledge — Discourse forum threads, GitHub issues, pull requests and discussions of the scvi-tools ecosystem repos, and the scvi-tools / scviva-tools website blogs.

No runtime model execution — pure knowledge layer. Works with Claude Desktop, Cursor, and any MCP-compatible client.

Docs: scvi-tools-mcp.readthedocs.io

---

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "scvi-tools": {
      "command": "uvx",
      "args": ["scvi-tools-mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add scvi-tools-mcp -s user -- uvx scvi-tools-mcp

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.scvi-tools-mcp]
command = "uvx"
args   = ["scvi-tools-mcp"]

Cursor / Windsurf / other clients

{ "command": "uvx", "args": ["scvi-tools-mcp"] }

Local install

pip install scvi-tools-mcp
scvi-tools-mcp

---

Tools

Tool	Description
recommend_model	Rank models by task and data type — start here
get_model_overview	Full model description, use cases, inputs, outputs
get_model_parameters	Key __init__ and train() parameters with defaults
get_setup_anndata_guide	Exact setup_anndata() call + required obs/var fields
validate_data_requirements	Pass/fail checklist for your AnnData against a model
list_tutorials	Browse tutorials by category
get_tutorial	Paginated tutorial content (code + prose, no outputs)
search_tutorials	Keyword search across all tutorials
get_api_reference	Signature + docstring for any public class or function
search_api	Search public symbols by keyword
get_workflow_template	Step-by-step code template for an analysis task
get_downstream_guide	Guide for DE, clustering, embedding, label transfer
list_hub_models	Browse official scvi-tools Hugging Face Hub models
get_hub_model	Inspect one pretrained HubModel repo
suggest_hub_models	Suggest Hub models for reference/query workflows
list_scviva_models	Browse scviva-tools spatial models (ResolVI, DestVI, …)
get_scviva_model	API reference + user guide for one scviva-tools model
list_scviva_tutorials	Browse scviva-tools tutorials
get_scviva_tutorial	Paginated scviva-tools tutorial content
list_scib_metrics	Browse scib-metrics integration-benchmarking metrics
get_scib_metric	API reference for one scib-metrics metric or benchmark
list_scib_metrics_tutorials	Browse scib-metrics tutorials
get_scib_metrics_tutorial	Paginated scib-metrics tutorial content
get_faq	Curated FAQ plus top community threads for a topic
search_knowledge	Cross-search all knowledge, incl. ranked community hits

---

Knowledge Sources

All knowledge is baked into the package as Markdown files at build time. No network calls at tool-call time.

Directory	Content
knowledge/models/	One .md per model — description, use case, parameters
knowledge/tutorials/	60+ tutorials converted from .ipynb (code + prose only)
knowledge/api/	Extracted class signatures and docstrings
knowledge/hub/models.json	Normalized Hugging Face Hub model registry snapshot
knowledge/hub/summary.md	Searchable summary of Hub model classes and modalities
knowledge/user_guide/	Narrative documentation from the scvi-tools user guide
knowledge/scviva_tools/models/	scviva-tools model docs (ResolVI, DestVI, scVIVA, …)
knowledge/scviva_tools/api/	Extracted scviva-tools class signatures and docstrings
knowledge/scviva_tools/tutorials/	scviva-tools tutorials converted from .ipynb
knowledge/scib_metrics/api/	Extracted scib-metrics function/class signatures
knowledge/scib_metrics/tutorials/	scib-metrics tutorials converted from .ipynb
knowledge/faq/github_<repo>_issues.md	GitHub issues snapshot per repo (last 3 years, accumulative)
knowledge/faq/github_<repo>_pulls.md	GitHub pull requests snapshot per repo (last 3 years, accumulative)
knowledge/faq/github_<repo>_discussions.md	GitHub Discussions snapshot per repo (last 3 years, accumulative)
knowledge/faq/discourse_threads.md	Discourse threads snapshot (last 3 years, accumulative)
knowledge/websites/<site>/	scvi-tools / scviva-tools website blog posts and pages (accumulative)

Community snapshots cover the scvi-tools Discourse forum and the GitHub repos scvi-tools, scvi-tutorials, scviva-tools, scib-metrics, scvi-colab and scvi-hub-models (issues, PRs with review comments, and discussions; content written by bots is excluded). They only grow: each refresh adds new and updated entries, and an entry is removed only once its last activity is more than three years old. search_knowledge and get_faq rank these Discourse/GitHub entries individually by relevance × recency, so the most recent answer to a question comes first, and list them separately from the curated docs. Website pages are never removed and are searched like the other documentation (no recency weighting).

---

Knowledge Refresh (CI)

Automated GitHub Actions jobs keep knowledge current — each opens a PR if a diff is found:

Workflow	Schedule	What it does
refresh_knowledge.yaml	1st of month	Merges GitHub issues/PRs/discussions, Discourse, websites
sync_tutorials.yaml	1st of month	Fetches new .ipynb from scvi-tools, converts to .md
sync_model_knowledge.yaml	1st of month	Checks CHANGELOG, regenerates model docs for changed models
sync_huggingface_hub.yaml	Quarterly	Refreshes the scvi-tools Hugging Face Hub model registry
sync_scviva_tools_knowledge.yaml	1st of month	Regenerates scviva-tools model/API docs from main
sync_scviva_tools_tutorials.yaml	1st of month	Fetches new .ipynb from scviva-tools, converts to .md
sync_scib_metrics_knowledge.yaml	1st of month	Regenerates scib-metrics API docs from the latest release
sync_scib_metrics_tutorials.yaml	1st of month	Fetches new .ipynb from scib-metrics, converts to .md

All workflows also support workflow_dispatch for manual runs.

---

Development

git clone https://github.com/Yoseflab/scvi-tools-mcp
cd scvi-tools-mcp
pip install -e . --group dev
pytest

Rebuild knowledge manually

# Convert tutorials from a local scvi-tools checkout
python scripts/convert_notebooks.py /path/to/scvi-tools/docs/tutorials/notebooks \
    src/scvi_tools_mcp/knowledge/tutorials

# Extract API docs (requires scvi-tools installed)
pip install -e ".[scvi]"
python scripts/extract_api_docs.py

# Refresh community knowledge (incremental). The token is needed for GitHub Discussions
# (GraphQL) and avoids REST rate limits; export it so the flag variants below also get it.
export GITHUB_TOKEN=$(gh auth token)
python scripts/scrape_external.py
#   --only github|discourse   refresh one source
#   --repo OWNER/NAME         limit GitHub to one repo (repeatable)
#   --since 2023-11-01T00:00:00Z   re-fetch GitHub from a date (backfill)

# Sync the scvi-tools / scviva-tools website blog posts and pages
python scripts/sync_websites.py

# Refresh Hugging Face Hub model registry snapshot
python scripts/scrape_huggingface_hub.py

Adding a new model

1. Run scripts/extract_api_docs.py after updating scvi-tools.
2. Add the model name to MODEL_NAMES in src/scvi_tools_mcp/tools/_constants.py.
3. Add requirements to MODEL_REQUIREMENTS in _data_prep.py if needed.

---

License

BSD 3-Clause License

Copyright (c) 2026, Yosef Lab, Weizmann Institute of Science