taehojo/alphagenome-mcp

A Model Context Protocol (MCP) server that provides natural language access to Google DeepMind's AlphaGenome variant effect prediction API.

한국어 요약: Google DeepMind AlphaGenome API를 MCP 클라이언트(Claude Desktop, Claude Code, Gemini CLI, Cursor, Windsurf 등)에서 자연어로 사용할 수 있게 해주는 MCP 서버입니다. 유전체 변이의 조절 효과, 병원성, 조직별 영향을 분석할 수 있습니다. 한국어 전체 문서 보기

Overview

AlphaGenome MCP Server provides a natural language interface to Google DeepMind's AlphaGenome variant effect prediction API. Query genomic variants using plain English instead of writing Python code, designed for exploratory analysis and rapid prototyping.

Key Features:

• Natural Language Interface: Query variants using plain English instead of writing code
• Wrapper Architecture: 20 specialized tools built as wrappers around a single API endpoint
• Comprehensive Analysis: Access all AlphaGenome modalities (RNA-seq, ChIP-seq, ATAC-seq, splicing, etc.)
• Research Tool: Designed for exploratory genomics research and variant prioritization

⚡ Quick Start

Get started in 3 minutes:

1. Install dependencies

   pip install alphagenome numpy
   

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

   claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY
   

   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 (takes 30-60 seconds)

   You'll get a detailed report with pathogenicity scores, expression impacts, and splicing effects.

Want more? Check out 20 specialized 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
└─────────────────────────┘

Wrapper Pattern

All 20 tools are lightweight wrappers around the same predict_variant() API endpoint. They differ only in parameter configuration and output formatting:

# Same underlying API call
predict_variant(variant, interval, ontology_terms, requested_outputs)

# Different wrappers provide specialized views:
- assess_pathogenicity()    → Clinical scoring
- predict_tf_binding_impact() → TF binding only
- compare_variants()         → Side-by-side comparison
- generate_variant_report()  → Formatted report

Benefits of Wrapper Architecture:

• Single API implementation serves 20 different functions
• Specialized outputs through parameter configuration
• Easy maintenance (update once, all tools benefit)
• Consistent interface across all tools

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

Core Analysis

predict_variant_effect

Full regulatory impact prediction across all 11 modalities.

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

assess_pathogenicity

Clinical pathogenicity scoring with evidence breakdown.

"Use alphagenome to assess the pathogenicity of rs429358"

Result: Pathogenic (score: 1.0) with expression, splicing, and TF binding evidence.

Tissue-Specific Analysis

predict_tissue_specific

Compare variant effects across multiple tissues.

"Use alphagenome to compare rs429358 effects in brain and liver"

Result: Tissue-differential expression (brain: -0.23%, liver: +0.07%)

batch_tissue_comparison

Multi-variant × multi-tissue analysis.

"Use alphagenome to test 5 variants in brain, liver, and heart"

Variant Comparison

compare_variants

Direct side-by-side comparison.

"Use alphagenome to compare APOE ε4 (rs429358) vs ε2 (rs7412)"

compare_alleles

Compare different mutations at the same position.

"Use alphagenome to compare T>C, T>G, T>A at chr19:44908684"

compare_protective_risk

Compare protective vs risk alleles.

"Use alphagenome to compare APOE protective vs risk alleles"

compare_variants_same_gene

Rank variants within a gene.

"Use alphagenome to compare these 5 BRCA1 variants"

Modality-Specific Analysis

predict_splice_impact

Splicing effects only.

"Use alphagenome to analyze splicing impact of chr6:41129252C>T"

predict_expression_impact

Gene expression changes only.

"Use alphagenome to show expression impact of rs744373"

predict_tf_binding_impact

Transcription factor binding changes.

"Use alphagenome to show TF binding changes for rs429358"

predict_chromatin_impact

Chromatin accessibility changes.

"Use alphagenome to analyze chromatin impact of rs429358"

batch_modality_screen

Screen variants for specific effects.

"Use alphagenome to screen 20 variants for splicing effects"

Multiple Variant Processing

batch_score_variants

Rank multiple variants by regulatory impact.

"Use alphagenome to score these AD variants: rs429358, rs7412, rs75932628"

analyze_gwas_locus

Fine-mapping and causal variant identification.

"Use alphagenome to analyze GWAS locus with 10 variants"

batch_pathogenicity_filter

Filter variants by pathogenicity threshold.

"Use alphagenome to filter these 100 variants for pathogenicity > 0.7"

Regulatory Annotation

annotate_regulatory_context

Comprehensive regulatory context.

"Use alphagenome to annotate regulatory context of rs429358"

predict_allele_specific_effects

Allele-specific regulatory effects.

"Use alphagenome to show allele-specific effects for rs429358"

Clinical Reporting

generate_variant_report

Comprehensive clinical report.

"Use alphagenome to generate a clinical report for rs429358"

explain_variant_impact

Human-readable explanation.

"Use alphagenome to explain the impact of rs429358 in simple terms"

Installation

Requirements

• Node.js ≥18.0.0
• Python ≥3.8
• AlphaGenome API key from Google DeepMind
• Python packages: alphagenome, numpy

Setup

1. Install Python dependencies:

pip install alphagenome numpy

2. Configure for your MCP client:

claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY

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

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

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

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

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

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

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

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

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

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

Verification

Expected: Detailed regulatory impact report within 30-60 seconds.

Important: Always include "use alphagenome" in queries to explicitly invoke the server.

Usage Examples

All examples show actual API results from tests with Alzheimer's disease variants.

Pathogenicity Assessment

User: "Use alphagenome to assess the pathogenicity of rs429358"

Result:

{
  "variant": "chr19:44908684T>C",
  "classification": "PATHOGENIC",
  "pathogenicity_score": 1.0,
  "evidence": {
    "expression_impact": 0.0023,
    "splicing_impact": 0.0263,
    "tf_binding_impact": 24.0
  },
  "recommendation": "Further clinical evaluation recommended"
}

Tissue-Specific Analysis

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

Result:

{
  "variant": "chr19:44908684T>C",
  "tissue_results": {
    "brain": {
      "expression_impact": -0.0023,
      "impact_level": "high"
    },
    "liver": {
      "expression_impact": 0.0007,
      "impact_level": "high"
    }
  }
}

Interpretation: Tissue-differential effects. Brain shows downregulation (-0.23%) while liver shows upregulation (+0.07%).

Variant Comparison

User: "Use alphagenome to compare APOE ε4 (rs429358) vs ε2 (rs7412)"

Result:

{
  "variant1": {
    "id": "chr19:44908684T>C",
    "impact": "high",
    "expression_fc": -0.0023
  },
  "variant2": {
    "id": "chr19:44908822C>T",
    "impact": "high",
    "expression_fc": 0.0012
  },
  "comparison": {
    "more_severe": "chr19:44908684T>C"
  }
}

TF Binding Analysis

User: "Use alphagenome to show TF binding changes for rs429358"

Result:

{
  "variant": "chr19:44908684T>C",
  "tf_binding": [{
    "change": 24.0
  }],
  "impact_level": "high"
}

Allele Comparison

User: "Use alphagenome to compare T>C, T>G, T>A at chr19:44908684"

Result:

{
  "position": "chr19:44908684",
  "allele_comparisons": {
    "T>C": { "expression_fc": -0.0023, "impact": "high" },
    "T>G": { "expression_fc": -0.0038, "impact": "high" },
    "T>A": { "expression_fc": 0.0035, "impact": "high" }
  }
}

Interpretation: All three alternative alleles show high regulatory impact with varying expression effects.

Clinical Report

User: "Use alphagenome to generate a clinical report for rs429358"

Result:

VARIANT REPORT: chr19:44908684T>C (rs429358)

Classification: PATHOGENIC
Pathogenicity Score: 1.0

Evidence Summary:
- Expression Impact: 0.0023 (fold change)
- Splicing Impact: 0.0263 (delta score)
- TF Binding Impact: 24.0 (change score)

Recommendation: Further clinical evaluation recommended

Performance

• First call: 30-60 seconds (initialization), subsequent calls: 8-15 seconds per variant
• 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)
├── tools.ts              # MCP tool definitions
├── types.ts              # TypeScript type definitions
└── utils/
    ├── validation.ts     # Input validation (Zod schemas)
    └── formatting.ts     # Output formatting
scripts/
└── alphagenome_bridge.py # Python bridge to AlphaGenome SDK

Testing

npm run lint           # ESLint check
npm run typecheck      # TypeScript type checking
npm run build          # Compile to build/

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{avsec2025alphagenome,
  title = {AlphaGenome: advancing regulatory variant effect prediction with a unified DNA sequence model},
  author = {Avsec, Žiga and Latysheva, Natasha and Cheng, Jun and others},
  journal = {bioRxiv},
  year = {2025}
}

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 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

AlphaGenome MCP 서버

Google DeepMind의 AlphaGenome을 자연어로 사용할 수 있게 해주는 MCP 서버

개요

유전체 변이(genomic variant)의 조절 효과를 AI로 예측하는 AlphaGenome API를 MCP 클라이언트(Claude Desktop, Claude Code, Gemini CLI, Cursor, Windsurf 등)에서 자연어로 사용할 수 있습니다. Python 코드를 작성하지 않고 평범한 한국어나 영어로 변이를 분석할 수 있으며, 탐색적 분석과 빠른 프로토타이핑에 최적화되어 있습니다.

주요 기능

• 🧬 변이 효과 예측: 11가지 분자 양식(RNA-seq, ChIP-seq, ATAC-seq, 스플라이싱 등)에서 조절 영향 분석
• 🏥 병원성 평가: 임상 점수 산출 및 필터링
• 🔬 조직별 분석: 뇌, 간, 심장 등 여러 조직에서의 효과 프로파일링
• 📊 배치 처리: 대용량 변이 우선순위 지정
• 💬 자연어 인터페이스: 코딩 없이 rsID나 염색체 좌표로 쿼리
• 🔧 20가지 전문 도구: 단일 API를 감싸는 래퍼 아키텍처

⚡ 빠른 시작

3분 안에 시작하기:

1. Python 패키지 설치

   pip install alphagenome numpy
   

2. MCP 클라이언트에 추가 (Claude Desktop, Claude Code, Gemini CLI, Cursor, Windsurf 지원)

   claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY
   

   다른 MCP 클라이언트는 설치 방법 참고

3. 첫 번째 쿼리 실행

   MCP 클라이언트를 재시작하고 다음을 시도하세요:

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

   또는 한국어로:

   "alphagenome을 사용해서 chr19:44908684T>C를 분석해줘"
   

4. 결과 확인 (30-60초 소요)

   병원성 점수, 발현 영향, 스플라이싱 효과가 포함된 상세 보고서가 생성됩니다.

더 알아보기: 20가지 전문 도구 확인

시스템 구조

┌─────────────────────────┐
│  연구자                  │
└───────────┬─────────────┘
            │ 자연어 쿼리
            ↓
┌─────────────────────────┐
│  Claude Desktop         │ ← MCP 클라이언트
└───────────┬─────────────┘
            │ JSON-RPC (stdio)
            ↓
┌─────────────────────────┐
│  MCP 서버 (TypeScript)  │ ← 도구 라우팅, 검증
└───────────┬─────────────┘
            │ subprocess
            ↓
┌─────────────────────────┐
│  Python 브리지          │ ← AlphaGenome SDK 인터페이스
└───────────┬─────────────┘
            │ HTTP
            ↓
┌─────────────────────────┐
│  AlphaGenome API        │ ← Google DeepMind 서비스
└─────────────────────────┘

설치 방법

요구사항

• Node.js ≥18.0.0
• Python ≥3.8
• AlphaGenome API 키 (Google DeepMind에서 발급)
• Python 패키지: alphagenome, numpy

설치

1. Python 패키지 설치:

pip install alphagenome numpy

2. MCP 클라이언트 설정:

claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY

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

"alphagenome으로 chr19:44908684T>C를 분석해줘"

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

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

사용 예시

병원성 평가

"rs429358의 병원성을 평가해줘"

결과: 병원성 점수 1.0, 발현 영향 0.0023, 스플라이싱 영향 0.0263

조직별 분석

"rs429358의 뇌와 간에서의 효과를 비교해줘"

결과: 뇌에서 -0.23% 하향조절, 간에서 +0.07% 상향조절

변이 비교

"APOE ε4 (rs429358)와 ε2 (rs7412)를 비교해줘"

결과: ε4가 더 심각한 영향 (발현 변화 -0.0023 vs +0.0012)

스플라이싱 영향

"chr6:41129252C>T의 스플라이싱 영향을 분석해줘"

배치 처리

"이 10개 변이를 병원성 점수로 정렬해줘"

성능

• 첫 호출: 30-60초 (초기화), 이후 호출: 변이당 8-15초
• 분석 양식: 11가지 (RNA-seq, CAGE, PRO-cap, 스플라이스 사이트, DNase, ATAC, 히스톤 변형, 전사인자 결합, 접촉 맵)

인용

이 소프트웨어를 연구에 사용하신다면 다음과 같이 인용해주세요:

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

AlphaGenome 모델:

@article{avsec2025alphagenome,
  title = {AlphaGenome: advancing regulatory variant effect prediction with a unified DNA sequence model},
  author = {Avsec, Žiga and Latysheva, Natasha and Cheng, Jun and others},
  journal = {bioRxiv},
  year = {2025}
}

상세 문서

전체 도구 목록, 상세 사용 예제, API 응답 형식, 개발 가이드는 영문 문서를 참고하세요.

라이선스

MIT License - Copyright (c) 2025 Taeho Jo

링크

• npm 패키지: https://www.npmjs.com/package/@jolab/alphagenome-mcp
• GitHub 저장소: https://github.com/taehojo/alphagenome-mcp
• AlphaGenome: https://deepmind.google/discover/blog/alphagenome/
• Model Context Protocol: https://modelcontextprotocol.io/