![Logo](logo.png)
# Unofficial GTEx Portal MCP Server

A comprehensive Model Context Protocol (MCP) server providing access to the GTEx (Genotype-Tissue Expression) Portal API. This server enables AI assistants to query and analyze genomics data from the GTEx project through **25 specialized tools** across three categories.

**Developed by [Augmented Nature](https://augmentednature.ai)**

## Overview

The GTEx Portal contains gene expression and regulatory data from 54 non-diseased tissue sites across nearly 1000 individuals. This MCP server provides structured access to:

- **Expression Analysis**: Gene expression patterns and tissue specificity (7 tools)
- **Association Analysis**: eQTL/sQTL analysis and genetic associations (6 tools)
- **Reference/Dataset**: Gene/variant lookups and metadata (12 tools)

## 🧬 Complete Tool Suite (25/25 Implemented)

### Expression Analysis Tools (7 tools)
- `get_gene_expression` - Get gene expression data across tissues for specific genes
- `get_median_gene_expression` - Get median gene expression levels across tissues
- `get_top_expressed_genes` - Get top expressed genes in specific tissues
- `get_tissue_specific_genes` - Get genes with tissue-specific expression patterns
- `get_clustered_expression` - Get clustered gene expression data for visualization
- `calculate_expression_correlation` - Calculate Pearson correlation between genes across tissues
- `get_differential_expression` - Get differential gene expression between tissue groups

### Association Analysis Tools (6 tools)
- `get_eqtl_genes` - Get genes with eQTL associations for genomic regions
- `get_single_tissue_eqtls` - Get single-tissue eQTL results for genes
- `calculate_dynamic_eqtl` - Calculate dynamic eQTL effects across tissues
- `get_multi_tissue_eqtls` - Get multi-tissue eQTL meta-analysis results
- `get_sqtl_results` - Get splicing QTL (sQTL) results for genes
- `analyze_ld_structure` - Analyze linkage disequilibrium structure around variants

### Reference/Dataset Tools (12 tools)
- `search_genes` - Search for genes by symbol, name, or description
- `get_gene_info` - Get detailed information about specific genes
- `get_variants` - Get genetic variants in genomic regions
- `get_tissue_info` - Get information about GTEx tissues and sample counts
- `get_sample_info` - Get GTEx sample metadata and demographics
- `get_subject_phenotypes` - Get subject phenotype data and demographics
- `validate_gene_id` - Validate and normalize gene identifiers
- `validate_variant_id` - Validate variant identifiers and genomic coordinates
- `get_dataset_info` - Get information about available GTEx datasets
- `search_transcripts` - Search for gene transcripts and isoforms
- `get_gene_ontology` - Get Gene Ontology annotations for genes
- `convert_coordinates` - Convert between genomic coordinate systems (hg19/hg38)

## 🚀 Installation

1. Clone or download the server files
2. Install dependencies:
```bash
cd gtex-server
npm install
```

3. Build the server:
```bash
npm run build
```

## Usage

### Running the Server

Start the server for testing:
```bash
npm run dev
```

Use the MCP inspector for development:
```bash
npm run inspector
```

### Integrating with Claude Desktop

Add the server to your Claude Desktop configuration file:

**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**On Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gtex-server": {
      "command": "node",
      "args": ["/path/to/gtex-server/build/index.js"]
    }
  }
}
```

Replace `/path/to/gtex-server` with the actual path to your server installation.

## 📊 Example Usage

### Search for Genes
```
Search for genes related to "BRCA1" or "insulin signaling"
```

### Gene Expression Analysis
```
Get median gene expression for ENSG00000012048.20 (BRCA1) across all tissues
```

### Tissue-Specific Analysis
```
Find tissue-specific genes in Brain_Cortex and compare with Muscle_Skeletal
```

### eQTL Analysis
```
Find genes with eQTL associations in genomic region chr17:43000000-43200000
```

### Expression Correlation
```
Calculate expression correlation between BRCA1 and BRCA2 across tissues
```

### Coordinate Conversion
```
Convert genomic coordinates from hg38 to hg19: chr1:1500000
```

## 🔬 Scientific Applications

This server enables comprehensive genomics research including:

- **Tissue Expression Profiling**: Identify genes with tissue-specific or tissue-enriched expression
- **Co-expression Analysis**: Find genes with correlated expression patterns
- **eQTL Mapping**: Discover expression quantitative trait loci and regulatory variants  
- **Comparative Genomics**: Compare expression across different tissue types
- **Functional Annotation**: Link genes to biological processes via Gene Ontology
- **Variant Analysis**: Explore genetic variation and its impact on gene expression

## 🗄️ API Data Source

This server connects to the GTEx Portal API v2:
- **Base URL**: https://gtexportal.org/api/v2/
- **Documentation**: https://gtexportal.org/api/v2/redoc
- **Data**: GTEx v8 dataset (15,201 RNA-Seq samples from 54 tissues, 948 donors)
- **Genome Build**: GRCh38/hg38

## 📋 Data Types and Formats

### Gene Identifiers
- **GENCODE IDs**: e.g., `ENSG00000012048.20` (BRCA1)
- **Gene Symbols**: e.g., `BRCA1`, `TP53`, `INSR`

### Tissue Identifiers  
- **Tissue Site Detail IDs**: e.g., `Muscle_Skeletal`, `Brain_Cortex`, `Heart_Left_Ventricle`
- Use `get_tissue_info` tool to see all 54 available tissues

### Genomic Coordinates
- **Chromosome**: e.g., `chr17`, `chrX`, `chrY`
- **Positions**: 1-based genomic coordinates
- **Genome Build**: GRCh38/hg38 (with hg19 conversion available)

### Expression Values
- **Units**: TPM (Transcripts Per Million)
- **Statistics**: Mean, median, standard deviation across samples
- **Detection**: Percentage of samples with detectable expression

## ⚡ Performance & Reliability

- **Error Handling**: Comprehensive validation and graceful error recovery
- **Rate Limiting**: Automatic handling of API rate limits
- **Timeouts**: 30-second timeouts with retry logic
- **Caching**: Intelligent caching to improve response times
- **Pagination**: Automatic handling of large result sets
- **Validation**: Input parameter validation and normalization

## 🛠️ Development

### Project Structure
```
gtex-server/
├── src/
│   ├── index.ts                      # Main MCP server with tool registration
│   ├── types/gtex-types.ts          # Complete TypeScript type definitions
│   ├── utils/api-client.ts          # GTEx API client with comprehensive methods
│   └── handlers/
│       ├── expression-handlers.ts    # 7 expression analysis tools
│       ├── association-handlers.ts   # 6 eQTL/sQTL analysis tools  
│       └── reference-handlers.ts     # 12 reference/lookup tools
├── build/                           # Compiled JavaScript output
├── test-complete-server.js         # Comprehensive testing script
├── package.json                     # Dependencies and build scripts
└── tsconfig.json                    # TypeScript configuration
```

### Development Commands
```bash
# Build the project
npm run build

# Run in development mode with auto-reload
npm run dev

# Watch for changes during development
npm run watch

# Test all 25 tools
node test-complete-server.js
```

### Technical Implementation

- **Language**: TypeScript with ES modules
- **Framework**: Model Context Protocol SDK v0.6.0
- **Architecture**: Modular design with separate handler classes
- **API Client**: Axios with comprehensive error handling
- **Data Processing**: Statistical analysis and data formatting
- **Type Safety**: Complete type definitions for all GTEx API responses

## 📚 References

- [GTEx Portal](https://gtexportal.org/) - Main GTEx data portal
- [GTEx API Documentation](https://gtexportal.org/api/v2/redoc) - Complete API reference
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
- [GTEx Consortium Nature Paper](https://www.nature.com/articles/s41588-017-0004-9) - Primary publication
- [GTEx Analysis Methods](https://www.gtexportal.org/home/documentationPage#staticTextAnalysisMethods) - Statistical methods

## 🎯 Status: Production Ready

✅ **All 25 tools implemented and tested**  
✅ **Complete TypeScript implementation**  
✅ **Comprehensive error handling**  
✅ **Live GTEx Portal API integration**  
✅ **MCP 1.0 compliant**  
✅ **Ready for genomics research**

## 📄 License

MIT License - Feel free to use, modify, and distribute for research and commercial applications.

---

*This server bridges the GTEx Portal's extensive genomics database with the Model Context Protocol, enabling powerful genomics analysis through AI assistants.*