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
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 genesget_median_gene_expression- Get median gene expression levels across tissuesget_top_expressed_genes- Get top expressed genes in specific tissuesget_tissue_specific_genes- Get genes with tissue-specific expression patternsget_clustered_expression- Get clustered gene expression data for visualizationcalculate_expression_correlation- Calculate Pearson correlation between genes across tissuesget_differential_expression- Get differential gene expression between tissue groups
Association Analysis Tools (6 tools)
get_eqtl_genes- Get genes with eQTL associations for genomic regionsget_single_tissue_eqtls- Get single-tissue eQTL results for genescalculate_dynamic_eqtl- Calculate dynamic eQTL effects across tissuesget_multi_tissue_eqtls- Get multi-tissue eQTL meta-analysis resultsget_sqtl_results- Get splicing QTL (sQTL) results for genesanalyze_ld_structure- Analyze linkage disequilibrium structure around variants
Reference/Dataset Tools (12 tools)
search_genes- Search for genes by symbol, name, or descriptionget_gene_info- Get detailed information about specific genesget_variants- Get genetic variants in genomic regionsget_tissue_info- Get information about GTEx tissues and sample countsget_sample_info- Get GTEx sample metadata and demographicsget_subject_phenotypes- Get subject phenotype data and demographicsvalidate_gene_id- Validate and normalize gene identifiersvalidate_variant_id- Validate variant identifiers and genomic coordinatesget_dataset_info- Get information about available GTEx datasetssearch_transcripts- Search for gene transcripts and isoformsget_gene_ontology- Get Gene Ontology annotations for genesconvert_coordinates- Convert between genomic coordinate systems (hg19/hg38)
🚀 Installation
- Clone or download the server files
- Install dependencies:
cd gtex-server
npm install
- Build the server:
npm run build
Usage
Running the Server
Start the server for testing:
npm run dev
Use the MCP inspector for development:
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
{
"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_infotool 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
# 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 - Main GTEx data portal
- GTEx API Documentation - Complete API reference
- Model Context Protocol - MCP specification
- GTEx Consortium Nature Paper - Primary publication
- GTEx Analysis Methods - 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.