AlphaGenome基因组变异效应预测MCP服务

AlphaGenome MCP Server

AlphaGenome as a tool for Claude agents. A Model Context Protocol (MCP) server that lets an agent turn a researcher's question into an AlphaGenome analysis.

Demo

Ninety seconds in Claude Code, shown at 2x speed, with the published package and the real API. The video has no sound; pause it to read an answer.

https://github.com/user-attachments/assets/cbd083ee-53f9-4b35-b11e-3b33e10f7df9

The explanations in the video are written by Claude from the tool results. The tools themselves return scores and calibrated quantiles, and never a pathogenicity call.

Overview

A researcher asks a question; the agent decides which AlphaGenome calls answer it, runs them, and reads the results back. This server gives the agent the two ways AlphaGenome can be asked:

• The AlphaGenome Atlas for single-nucleotide variants. The Atlas holds precomputed predictions for every possible single-nucleotide substitution in the human genome, so a lookup answers in seconds and a whole region can be ranked without running the model.
• Live inference for indels and other variants the Atlas cannot precompute.

The server chooses between the two automatically, and every result states its source (source: atlas or source: live), so a precomputed score is never mistaken for a fresh model call or the other way round.

Key Features:

• Atlas first: single-nucleotide variants are answered from the precomputed Atlas; live inference runs only when it is needed
• Always says where the answer came from: source: atlas, source: live, or source: live (atlas fallback: <reason>)
• One shape for both sources: live inference uses the SDK's score_variant with its recommended variant scorers, which have the same names as the Atlas scorers, so an Atlas result and a live result can be read side by side
• AVI score and its attributions: the AlphaGenome Variant Impact score (AVI_SCORE) and its feature attributions are first-class outputs for single-nucleotide variants
• Region scans without the model: rank every substitution in a region by the AVI score
• 24 tools: 4 Atlas tools and 20 variant tools

These are model predictions for research prioritization, not clinical classifications. Every tool reports AlphaGenome's scores and calibrated quantiles as returned. No tool classifies a variant as pathogenic or benign, assigns a risk label, or states a percent change, on either path. Not for diagnosis or treatment decisions.

⚡ Quick Start

Get started in 3 minutes:

0. Get an API key at https://deepmind.google.com/science/alphagenome (free for non-commercial use). You need Node.js 18+ and Python 3.10+.

1. Install dependencies

   复制

   pip install alphagenome numpy
   

   If this fails, or you are on Windows, use a virtual environment: see Python environment.

2. Add to your MCP client (supports Claude Code, Claude Desktop, Gemini CLI, Cursor, Windsurf)

   复制

   claude mcp add alphagenome --env ALPHAGENOME_API_KEY=YOUR_API_KEY -- npx -y @jolab/alphagenome-mcp@latest
   

   See Installation for other MCP clients.

3. Run your first query

   Restart your MCP client and try:

   复制

   "Use alphagenome to analyze chr19:44908684T>C"
   

4. View results

   This is a single-nucleotide variant, so it is answered from the Atlas in a few seconds and the report starts with Source: atlas. An indel would run live inference instead (typically 3-10 seconds) and say Source: live.

Want more? Check out the 24 tools below.

Architecture

System Design

AlphaGenome MCP Server implements a multi-tier architecture:

┌─────────────────────────┐
│  Researcher             │
└───────────┬─────────────┘
            │ Natural language query
            ↓
┌─────────────────────────┐
│  Claude Desktop         │ ← MCP Client
└───────────┬─────────────┘
            │ JSON-RPC over stdio
            ↓
┌─────────────────────────┐
│  MCP Server (TypeScript)│ ← Tool routing, validation
└───────────┬─────────────┘
            │ subprocess
            ↓
┌─────────────────────────┐
│  Python Bridge          │ ← Interface to AlphaGenome SDK
└───────────┬─────────────┘
            │ HTTP
            ↓
┌─────────────────────────┐
│  AlphaGenome API        │ ← Google DeepMind's service
└─────────────────────────┘

Atlas or live inference

Six tools choose between the two on their own: predict_variant_effect, batch_score_variants, assess_pathogenicity, batch_pathogenicity_filter, generate_variant_report and explain_variant_impact. They take an optional source parameter:

The fallback is deliberately narrow. It happens only when the Atlas reports that it does not hold the variant. Authentication, rate limit, network and timeout errors are returned as errors, and so is a variant the Atlas rejects: if the reference base does not match hg38, the Atlas says which base it expected, and the server passes that message on instead of running the model on a mistyped variant. In a batch, each variant is routed on its own and the result reports how many came from each source and how many fell back. A mixed batch is reported as two separately ranked groups: the Atlas group is ranked by the AVI score by default, live inference has no AVI score, so one merged ranking would compare different quantities.

Two primitives, one shape

Every tool is a view over two primitives: score one variant and score many variants and rank them. Each is answered by the Atlas or by live inference, and both return the same thing: for each scorer, a matrix of rows (the variant, or one row per gene or junction) by tracks (tissues, cell types, assays), with a calibrated quantile for every score.

Atlas            client.query_variant(variant, requested_scorers=[...])
Live inference   client.score_variant(interval, variant, RECOMMENDED_VARIANT_SCORERS[...])
                 -> {scorer: AnnData}  ->  one shared summarizer  ->  ranked rows + source

The scorer names are the same on both sides (RNA_SEQ, CAGE, DNASE, CHIP_HISTONE, CHIP_TF, SPLICE_SITES, ...). The AVI scorers are the exception: the Atlas alone serves them. For chr17:49210289 C>T the two sources agree on the strongest track of five of the six default scorers, with scores that are close but not identical (DNASE in HeLa-S3: 2.778 from the Atlas, 2.846 live; CAGE in HeLa-S3: 1.866 and 2.121).

A matrix is never returned. One variant is thousands of numbers per scorer, so every result is the strongest cells, ranked, with the gene, tissue and assay of each.

Input Validation

All inputs undergo validation before API submission:

• Chromosomes: Pattern-matched for chr1-22, chrX, chrY
• Positions: Validated as positive integers
• Alleles: A/T/G/C nucleotide validation
• Tissue types: UBERON ontology term validation

Invalid inputs return human-readable error messages, enabling conversational error recovery.

Available Tools

AlphaGenome Atlas

Precomputed scores, no model call. Every Atlas response is a summary: ranked rows, never a full score matrix. One variant alone is thousands of numbers per scorer (61 genes x 371 tracks for RNA-seq at the APOE locus), so responses are capped at top_n rows (default 25, maximum 100) and at 40,000 characters.

atlas_list_scorers

The scorers the Atlas serves (22 at the time of writing), with the number of tracks and the assays behind each. Cached for the session.

"Which scorers does the AlphaGenome Atlas have?"

atlas_lookup_variant

Scores of one single-nucleotide variant: the strongest tracks per scorer, ranked by absolute score, with the gene, tissue or cell type, and assay of each.

"Look up chr19:44908684 T>C in the AlphaGenome Atlas"

atlas_lookup_variants

Up to 500 single-nucleotide variants in one call, ranked by absolute score. Variants the Atlas does not hold, and variants it rejects (for example a reference base that does not match hg38), are listed separately with the reason instead of failing the whole call.

"Rank these 200 GWAS SNPs by their Atlas scores"

atlas_scan_region

Every possible single-nucleotide substitution in a region, ranked by absolute score. Answers "which positions in this region matter most?" without running the model. At most 10,000 bp; up to 50,000 bp only with allow_large_region: true.

"Scan chr17:49209289-49211289 and show the 10 substitutions with the largest predicted effect"

Default scorers. Override with the scorers parameter; names come from atlas_list_scorers.

For batch_score_variants, the scoring_metric picks the Atlas scorer when scorers is not given: rna_seq uses RNA_SEQ, splice uses SPLICE_SITES, regulatory_impact and combined use AVI_SCORE.

The AVI score. The AlphaGenome Variant Impact (AVI) score combines AlphaGenome's predictions with AlphaMissense and other features into one number per variant. The Atlas serves it through the API as three scorers, and this server treats them as first-class outputs:

The AVI score exists for single-nucleotide variants only, because only the Atlas serves it. A live result has no AVI score, and says so rather than approximating one. Scores and quantiles are reported exactly as returned; they are not turned into a pathogenic or benign call.

Limits to know about.

• The Atlas API has a requests-per-minute quota, and a region scan uses one request per 32 bp. That is why a scan is limited to 10,000 bp unless allow_large_region is set. Long scans wait and retry when the quota is hit. If the time limit (ALPHAGENOME_TIMEOUT_MS) is reached first, the partial result is returned, marked Incomplete, with the range that was really scanned; it is never silently truncated.
• Scorers with one row per gene or junction (RNA_SEQ, SPLICE_JUNCTIONS, ...) return more data per request than the API allows for a region scan. Scan with AVI_SCORE first, then look up the top variants with atlas_lookup_variant.
• Human reference genome (hg38) only. Positions are 1-based.

Tools that choose between the Atlas and live inference

All six take source (auto, atlas, live) and scorers.

predict_variant_effect

The strongest tracks of each modality for one variant, with score, quantile, gene, tissue and assay. From the Atlas the AVI score is included. Optional output_types and tissue_type.

"Use alphagenome to analyze chr19:44908684T>C"

batch_score_variants

Up to 100 variants, each routed on its own, ranked by predicted effect. Reports how many came from each source and how many fell back.

"Use alphagenome to score these 50 variants and show the top 10"

assess_pathogenicity

Predicted effect size across modalities, and the AVI score from the Atlas. The name is kept for compatibility: it does not classify. classification is always null.

"Use alphagenome to assess rs429358"

batch_pathogenicity_filter

Keeps the variants whose largest absolute quantile reaches threshold (default 0.99), ranked, per source. A filter on predicted effect size, not on pathogenicity.

"Use alphagenome to keep the variants above the 99.9th percentile"

generate_variant_report

A fuller report of one variant: more rows per scorer and, from the Atlas, the AVI score with its feature attributions. A research summary, not a clinical report: no classification, no recommendation.

"Use alphagenome to generate a report for rs429358"

explain_variant_impact

Plain sentences that restate the numbers: the AVI score and its largest contributions, then the strongest effect of each modality ordered by quantile, with the direction for signed scorers. Descriptive only.

"Use alphagenome to explain the predicted effect of rs429358"

Live-inference tools

These run score_variant and work for single-nucleotide variants, indels and multi-nucleotide variants. Every result states source: live. Tools that take one variant accept an optional tissue_type (a name such as brain, or an ontology CURIE such as UBERON:0000955).

Rankings over several scorers use the largest absolute quantile, because quantiles are calibrated and the raw scores of different scorers are not on one scale. A ranking over one scorer uses its absolute score.

Installation

Requirements

• Node.js ≥18.0.0
• Python ≥3.10 (required by the alphagenome package)
• alphagenome ≥0.9.0 for the Atlas tools
• AlphaGenome API key: https://deepmind.google.com/science/alphagenome (free for non-commercial use)
• Python packages: alphagenome, numpy

Environment variables

Python environment

The server runs the AlphaGenome Python SDK in a subprocess, so it needs a Python 3.10+ interpreter that has alphagenome installed. A virtual environment is the reliable way to get one: it avoids the "externally managed environment" error of system Pythons on macOS and Linux, and on Windows, where python3 usually does not exist and python is often not on the PATH, it gives you a path to point at.

# macOS / Linux
python3 -m venv ~/.alphagenome-venv
~/.alphagenome-venv/bin/pip install alphagenome numpy

# Windows (PowerShell)
py -3 -m venv $HOME\.alphagenome-venv
& $HOME\.alphagenome-venv\Scripts\pip install alphagenome numpy

Then tell the server which interpreter to use with ALPHAGENOME_PYTHON:

claude mcp add alphagenome \
  --env ALPHAGENOME_API_KEY=YOUR_API_KEY \
  --env ALPHAGENOME_PYTHON=/Users/you/.alphagenome-venv/bin/python \
  -- npx -y @jolab/alphagenome-mcp@latest

In a JSON configuration it goes in the same env block as the key (use the full path; on Windows, double the backslashes):

"env": {
  "ALPHAGENOME_API_KEY": "YOUR_API_KEY",
  "ALPHAGENOME_PYTHON": "C:\\Users\\you\\.alphagenome-venv\\Scripts\\python.exe"
}

If alphagenome is installed for the python3 (or python) on your PATH, you can skip ALPHAGENOME_PYTHON.

Setup

1. Install Python dependencies (or use the virtual environment above):

pip install alphagenome numpy

2. Configure for your MCP client:

claude mcp add alphagenome --env ALPHAGENOME_API_KEY=YOUR_API_KEY -- npx -y @jolab/alphagenome-mcp@latest

"Use alphagenome to analyze chr19:44908684T>C"

{
  "mcpServers": {
    "alphagenome": {
      "command": "npx",
      "args": ["-y", "@jolab/alphagenome-mcp@latest"],
      "env": { "ALPHAGENOME_API_KEY": "YOUR_API_KEY" }
    }
  }
}

"Use alphagenome to analyze chr19:44908684T>C"

{
  "mcpServers": {
    "alphagenome": {
      "command": "npx",
      "args": ["-y", "@jolab/alphagenome-mcp@latest"],
      "env": { "ALPHAGENOME_API_KEY": "YOUR_API_KEY" }
    }
  }
}

"Use alphagenome to analyze chr19:44908684T>C"

{
  "mcpServers": {
    "alphagenome": {
      "command": "npx",
      "args": ["-y", "@jolab/alphagenome-mcp@latest"],
      "env": { "ALPHAGENOME_API_KEY": "YOUR_API_KEY" }
    }
  }
}

"Use alphagenome to analyze chr19:44908684T>C"

{
  "mcpServers": {
    "alphagenome": {
      "command": "npx",
      "args": ["-y", "@jolab/alphagenome-mcp@latest"],
      "env": { "ALPHAGENOME_API_KEY": "YOUR_API_KEY" }
    }
  }
}

"Use alphagenome to analyze chr19:44908684T>C"

Verification

1. Check that the client can start the server. In Claude Code:
   复制

   claude mcp list
   

   alphagenome: ... ✔ Connected means the server starts. It does not yet prove that Python and the key work; the first query does.
2. Restart your MCP client and ask:
   复制

   "Use alphagenome to analyze chr19:44908684T>C"
   

   Expected: a report that starts with Source: atlas within a few seconds. An indel (for example chr17:49210289 CCC>C) says Source: live and typically takes 3-10 seconds.

Troubleshooting

The server reports problems as tool errors and keeps running. The message tells you which case you are in:

Tip: say "use alphagenome" in a query when the client does not pick the server on its own.

Usage Examples

All examples are actual results from the API (September 2026) for the two APOE variants that define the ε4 and ε2 alleles.

One variant, from the Atlas

User: "Use alphagenome to assess rs429358" (chr19:44908684 T>C)

{
  "source": "atlas",
  "variant": "chr19:44908684:T>C",
  "avi_score": { "score": 0.4999, "quantile": 0.9869896 },
  "strongest_effects": [
    { "scorer": "RNA_SEQ", "score": -0.038891, "quantile": -0.9996803, "where": "APOE, psoas muscle, polyA plus RNA-seq" },
    { "scorer": "CAGE", "score": 0.077866, "quantile": 0.9774153, "where": "pons, hCAGE" },
    { "scorer": "DNASE", "score": 0.12269, "quantile": 0.9463574, "where": "brain, DNase-seq" },
    { "scorer": "CHIP_HISTONE", "score": 0.13507, "quantile": 0.9953638, "where": "H3K27me3, common myeloid progenitor, CD34-positive, Histone ChIP-seq" },
    { "scorer": "CHIP_TF", "score": -0.16594, "quantile": -0.9972084, "where": "MYC, K562, TF ChIP-seq" },
    { "scorer": "SPLICE_SITES", "score": 0.022699, "quantile": 0.9561927, "where": "APOE" }
  ],
  "largest_abs_quantile": 0.9996803,
  "classification": null
}

The same variant, explained

User: "Use alphagenome to explain the predicted effect of rs429358"

AlphaGenome Variant Impact (AVI) score: 0.4999 (quantile 0.9869896).
Largest contributions to the AVI score: CACTUS_241_WAY (0.2944), PHASTCONS_470_WAY (0.14471), ALPHAMISSENSE (0.029138).
RNA_SEQ: largest predicted effect in APOE, psoas muscle, polyA plus RNA-seq, score -0.038891, quantile -0.9996803 (negative: predicted lower with the alternate allele than the reference).
CHIP_TF: largest predicted effect in MYC, K562, TF ChIP-seq, score -0.16594, quantile -0.9972084 (negative: ...).
...

An indel, by live inference

User: "Use alphagenome to analyze the deletion chr17:49210289 CCC>C"

**Variant**: chr17:49210289:CCC>C
**Source**: live
**Note**: Live inference because: deletion (CCC>C); the Atlas covers single-nucleotide substitutions only.

## RNA_SEQ
61 row(s) x 371 track(s); largest absolute score 0.8843, median 9.28e-4.

| Score | Quantile | Where |
|---|---|---|
| -0.8843 | -0.9999997 | ABI3, cardiac atrium fibroblast, total RNA-seq |

The same SNV from both sources

chr17:49210289 C>T with source: atlas and with source: live, strongest track per scorer:

The numbers are close, not identical: the Atlas was computed ahead of time and the live call runs the model now.

Two variants side by side

User: "Use alphagenome to compare APOE rs429358 and rs7412"

{
  "source": "live",
  "variants": [
    { "label": "variant1", "variant": "chr19:44908684:T>C",
      "effects": [ { "scorer": "RNA_SEQ", "score": -0.037954, "quantile": -0.9996693, "where": "APOE, psoas muscle, polyA plus RNA-seq" }, "..." ] },
    { "label": "variant2", "variant": "chr19:44908822:C>T",
      "effects": [ { "scorer": "RNA_SEQ", "score": 0.035793, "quantile": 0.9997013, "where": "APOE, endothelial cell of umbilical vein, polyA plus RNA-seq" }, "..." ] }
  ],
  "larger_abs_quantile_by_scorer": { "RNA_SEQ": "variant2", "...": "..." }
}

Tissue-specific

User: "Use alphagenome to compare rs429358 in brain and liver"

In brain the strongest RNA-seq effect is on APOE (score -0.0084, quantile -0.9943216); DNase-seq in brain is 0.1224 (quantile 0.9463574) and in liver -0.004807 (quantile -0.1842174).

Filtering a mixed batch

User: "Use alphagenome to keep the variants above the 99th percentile: rs429358, rs7412, and the deletion chr17:49210289 CCC>C"

The two SNVs are answered from the Atlas and ranked by the AVI score (rs7412: 0.8636, quantile 0.995461, kept; rs429358: quantile 0.9869896, not kept). The deletion is answered by live inference (largest quantile 0.9999997, kept). The result reports the two groups separately: "source": "mixed", "answered_from": { "atlas": 2, "live": 1, "atlas_fallback": 0 }.

Performance

• Atlas: 2-5 seconds per variant, about 7 seconds for a 2,000 bp region scan (with AVI_SCORE)
• Live inference: typically 3-10 seconds per variant (measured through the server, September 2026; depends on API load)
• Modalities: 11 (RNA-seq, CAGE, PRO-cap, splice sites, DNase, ATAC, histone mods, TF binding, contact maps)

Development

Build from Source

git clone https://github.com/taehojo/alphagenome-mcp.git
cd alphagenome-mcp
npm install
pip install -r requirements.txt
npm run build

Project Structure

src/
├── index.ts              # MCP server entry point
├── alphagenome-client.ts # API client (Python bridge, timeout, interpreter choice)
├── routing.ts            # Atlas or live inference: the rule, as pure functions
├── variant-tools.ts      # The 20 variant tools, over two primitives and a narrow backend interface
├── tools.ts              # MCP tool definitions
├── types.ts              # TypeScript type definitions
├── tests/                # Unit tests (no API key needed)
└── utils/
    ├── config.ts         # Environment variables
    ├── validation.ts     # Input validation (Zod schemas)
    └── formatting.ts     # One set of formatters for both sources, and the size cap
scripts/
├── alphagenome_bridge.py # Bridge: one JSON request in, one JSON response out
├── atlas_actions.py      # Atlas lookups and region scans
├── live_actions.py       # Live inference with score_variant
├── summaries.py          # The summarizer shared by both sources (numpy only)
└── tests/                # Python unit tests for the summarizer

Testing

npm test               # Build, then run the TypeScript unit tests (no API key needed)
npm run test:python    # Python unit tests for the shared summarizer (numpy and pandas only)
npm run docs:api       # Regenerate docs/API.md from the tool definitions in src/tools.ts
npm run lint           # ESLint check
npm run typecheck      # TypeScript type checking
npm run build          # Compile to build/

Roadmap

Not in this release, and not promised by any tool above:

• Combinations of variants: scoring several variants together on one haplotype, rather than one at a time.
• Custom sequences: predictions for a sequence the caller supplies, rather than a variant on the reference genome.

Both need live inference and neither can be precomputed, so they fit the same design: the Atlas where it can answer, the model where it cannot, and the source on every result.

Why this server exists

From a microglia gene to a variant map in about 60 seconds. The research workflow this server came from: which non-coding variants near ABI3 change its expression, answered with a traditional pipeline and with one sentence in Claude Code. Click the image for full resolution.

AlphaGenome at study scale

Rare variants and AlphaGenome-predicted regulatory impact in 85 Alzheimer's disease genes: an interactive browser of the rare variants (MAF < 1%) in 85 AD-associated genes from ADSP whole-genome sequencing, scored with AlphaGenome across eight regulatory modalities and compared with case-control allele frequencies in 24,595 ADSP R4 participants, with an independent assessment in 11,545 ADSP R5 participants (Jo et al., manuscript under review). Code and the 9,943-variant analysis table: taehojo/rarevariants.

The scores in that study were computed with the AlphaGenome Python SDK directly, not with this server, and before its 0.3.0 scoring. They are not output of this server.

Citation

If you use this software in your research, please cite:

@software{jo2025alphagenome_mcp,
  author = {Jo, Taeho},
  title = {AlphaGenome MCP Server},
  year = {2025},
  url = {https://github.com/taehojo/alphagenome-mcp},
  version = {0.2.0}
}

AlphaGenome model:

@article{avsec2026alphagenome,
  title = {Advancing regulatory variant effect prediction with {AlphaGenome}},
  author = {Avsec, Žiga and Latysheva, Natasha and Cheng, Jun and others},
  journal = {Nature},
  volume = {649},
  number = {8099},
  pages = {1206--1218},
  year = {2026},
  doi = {10.1038/s41586-025-10014-0}
}

Acknowledgments

• Google DeepMind for developing and providing access to the AlphaGenome API
• Anthropic for developing the Model Context Protocol specification and Claude Desktop

License

MIT License - Copyright (c) 2025 Taeho Jo

See LICENSE file for details.

Links

• npm Package: https://www.npmjs.com/package/@jolab/alphagenome-mcp
• GitHub Repository: https://github.com/taehojo/alphagenome-mcp
• AlphaGenome: https://deepmind.google/discover/blog/alphagenome/
• Model Context Protocol: https://modelcontextprotocol.io/
• Claude Desktop: https://claude.ai/download