README.md•22 kB
# AlphaGenome MCP Server
<p align="center">
<a href="#english">English</a> •
<a href="#korean">한국어</a>
</p>
[](https://www.npmjs.com/package/@jolab/alphagenome-mcp)
[](https://opensource.org/licenses/MIT)
<div id="english">
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 서버입니다. 유전체 변이의 조절 효과, 병원성, 조직별 영향을 분석할 수 있습니다. [한국어 전체 문서 보기](#korean)
## 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**
```bash
pip install alphagenome numpy
```
2. **Add to your MCP client** (supports Claude Desktop, Claude Code, Gemini CLI, Cursor, Windsurf)
```bash
claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY
```
See [Installation](#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](#available-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:
```python
# 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:**
```bash
pip install alphagenome numpy
```
**2. Configure for your MCP client:**
<details>
<summary><b>Claude Desktop</b></summary>
**Recommended method:**
```bash
claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY
```
**Or manually add to `~/.config/claude/claude_desktop_config.json`:**
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**Test:**
```
"Use alphagenome to analyze chr19:44908684T>C"
```
</details>
<details>
<summary><b>Claude Code</b></summary>
Add to `~/.config/claude/claude_code_config.json`:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**Test:**
```
"Use alphagenome to analyze chr19:44908684T>C"
```
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**Test:**
```
"Use alphagenome to analyze chr19:44908684T>C"
```
</details>
<details>
<summary><b>Cursor</b></summary>
Add to `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**Test:**
```
"Use alphagenome to analyze chr19:44908684T>C"
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Add to your Windsurf settings JSON:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**Test:**
```
"Use alphagenome to analyze chr19:44908684T>C"
```
</details>
### 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```bash
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
```bash
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:
```bibtex
@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:
```bibtex
@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 [LICENSE](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
</div>
---
<div id="korean">
# AlphaGenome MCP 서버
> Google DeepMind의 AlphaGenome을 자연어로 사용할 수 있게 해주는 MCP 서버
[](https://www.npmjs.com/package/@jolab/alphagenome-mcp)
[](https://opensource.org/licenses/MIT)
## 개요
유전체 변이(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 패키지 설치**
```bash
pip install alphagenome numpy
```
2. **MCP 클라이언트에 추가** (Claude Desktop, Claude Code, Gemini CLI, Cursor, Windsurf 지원)
```bash
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 패키지 설치:**
```bash
pip install alphagenome numpy
```
**2. MCP 클라이언트 설정:**
<details>
<summary><b>Claude Desktop</b></summary>
**권장 방법:**
```bash
claude mcp add alphagenome -- npx -y @jolab/alphagenome-mcp@latest --api-key YOUR_API_KEY
```
**수동 설정 (`~/.config/claude/claude_desktop_config.json`):**
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
**테스트:**
```
"alphagenome으로 chr19:44908684T>C를 분석해줘"
```
</details>
<details>
<summary><b>Claude Code</b></summary>
`~/.config/claude/claude_code_config.json`에 추가:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
프로젝트 루트의 `.cursor/mcp.json`에 추가:
```json
{
"mcpServers": {
"alphagenome": {
"command": "npx",
"args": ["-y", "@jolab/alphagenome-mcp@latest", "--api-key", "YOUR_API_KEY"]
}
}
}
```
</details>
## 사용 예시
### 병원성 평가
```
"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, 히스톤 변형, 전사인자 결합, 접촉 맵)
## 인용
이 소프트웨어를 연구에 사용하신다면 다음과 같이 인용해주세요:
```bibtex
@software{jo2025alphagenome_mcp,
author = {Jo, Taeho},
title = {AlphaGenome MCP Server},
year = {2025},
url = {https://github.com/taehojo/alphagenome-mcp},
version = {0.2.0}
}
```
AlphaGenome 모델:
```bibtex
@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 응답 형식, 개발 가이드는 [영문 문서](#english)를 참고하세요.
## 라이선스
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/
</div>