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

A comprehensive Model Context Protocol (MCP) server that provides access to the Ensembl REST API for genomic data, comparative genomics, and biological annotations.

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

## Overview

This server enables seamless access to Ensembl's vast genomic database through a standardized MCP interface. It supports gene lookups, sequence retrieval, variant analysis, comparative genomics, regulatory features, and much more across multiple species.

## Features

### Gene & Transcript Information

- **Gene Lookup**: Get detailed gene information by Ensembl ID or gene symbol
- **Transcript Analysis**: Retrieve all transcripts for a gene with structural details
- **Gene Search**: Search genes by name, description, or identifier with filtering options

### Sequence Data

- **Genomic Sequences**: Extract DNA sequences for any genomic region or feature
- **CDS Sequences**: Get coding sequences for specific transcripts
- **Sequence Translation**: Translate DNA sequences to protein sequences
- **Repeat Masking**: Support for hard and soft repeat masking

### Comparative Genomics

- **Homolog Detection**: Find orthologous and paralogous genes across species
- **Phylogenetic Trees**: Generate gene family trees in multiple formats
- **Cross-Species Analysis**: Compare genes and genomes across different organisms

### Variant Data

- **Variant Retrieval**: Get genetic variants in genomic regions
- **Consequence Prediction**: Predict variant effects on genes and transcripts
- **Population Genetics**: Access allele frequencies and population data

### Regulatory Features

- **Regulatory Elements**: Access enhancers, promoters, and TFBS data
- **Motif Features**: Get transcription factor binding motifs
- **Cell Type Context**: Filter regulatory features by cell type

### Cross-References & Annotations

- **External Database Links**: Get cross-references to PDB, EMBL, RefSeq, etc.
- **Coordinate Mapping**: Convert coordinates between genome assemblies
- **Ontology Terms**: Access GO terms and functional annotations

### Species & Assembly Information

- **Species Lists**: Browse available species and assemblies
- **Assembly Statistics**: Get genome assembly information and statistics
- **Karyotype Data**: Access chromosome information and banding patterns

### Batch Processing

- **Batch Gene Lookup**: Process multiple genes simultaneously
- **Batch Sequence Fetch**: Retrieve sequences for multiple regions efficiently

## Installation

```bash
# Clone or download the server files
cd ensembl-server

# Install dependencies
npm install

# Build the server
npm run build
```

## Usage with Claude Desktop

### Setup Instructions

1. **Build the server** (if not already done):

   ```bash
   npm run build
   ```

2. **Add to Claude Desktop configuration**:

   - Open Claude Desktop
   - Go to Settings → MCP Servers
   - Add a new server with:
     - **Name**: `ensembl`
     - **Command**: `node`
     - **Args**: `/path/to/ensembl-server/build/index.js`

3. **Restart Claude Desktop** to load the server

### Available Tools (25 total)

#### Gene & Transcript Information

- `lookup_gene` - Get detailed gene information by stable ID or symbol
- `get_transcripts` - Get all transcripts for a gene with detailed structure
- `search_genes` - Search for genes by name, description, or identifier

#### Sequence Data

- `get_sequence` - Get DNA sequence for genomic coordinates or gene/transcript ID
- `get_cds_sequence` - Get coding sequence (CDS) for a transcript
- `translate_sequence` - Translate DNA sequence to protein sequence

#### Comparative Genomics

- `get_homologs` - Find orthologous and paralogous genes across species
- `get_gene_tree` - Get phylogenetic tree for gene family

#### Variant Data

- `get_variants` - Get genetic variants in a genomic region
- `get_variant_consequences` - Predict consequences of variants on genes and transcripts

#### Regulatory Features

- `get_regulatory_features` - Get regulatory elements in genomic region
- `get_motif_features` - Get transcription factor binding motifs in genomic region

#### Cross-References & Annotations

- `get_xrefs` - Get external database cross-references for genes
- `map_coordinates` - Convert coordinates between genome assemblies

#### Species & Assembly Information

- `list_species` - Get list of available species and assemblies
- `get_assembly_info` - Get genome assembly information and statistics
- `get_karyotype` - Get chromosome information and karyotype

#### Batch Processing

- `batch_gene_lookup` - Look up multiple genes simultaneously
- `batch_sequence_fetch` - Fetch sequences for multiple regions or features

### Example Usage in Claude Desktop

Once connected, you can use natural language to access genomic data:

- "Look up the BRCA2 gene and get its sequence"
- "Find orthologs of TP53 in mouse"
- "Get variants in the region chr17:43044295-43125364"
- "Search for insulin-related genes"
- "Get the assembly information for human genome"
- "Translate this DNA sequence to protein: ATGAAACGC..."

## Supported Species

The server supports all species available in Ensembl, including:

- **Vertebrates**: Human, Mouse, Rat, Zebrafish, etc.
- **Plants**: Arabidopsis, Rice, Wheat, etc.
- **Fungi**: Yeast, etc.
- **Protists**: Various protist species
- **Metazoa**: Drosophila, C. elegans, etc.

Default species is `homo_sapiens` when not specified.

## Input Formats

### Genomic Regions

- `chr1:1000000-2000000` - Standard format
- `1:1000000-2000000` - Without 'chr' prefix
- `ENSG00000139618` - Feature IDs

### Gene/Transcript IDs

- Ensembl IDs: `ENSG00000139618`, `ENST00000380152`
- Gene symbols: `BRCA2`, `TP53`
- RefSeq IDs: `NM_000059`

## Output Formats

### Primary Formats

- **JSON**: Structured data (default for most tools)
- **FASTA**: Sequence data
- **GFF**: Genomic feature format
- **VCF**: Variant call format

### Tree Formats

- **JSON**: Structured tree data
- **Newick**: Standard phylogenetic format
- **PhyloXML**: Rich phylogenetic format

## Error Handling

The server provides comprehensive error handling:

- **Invalid Parameters**: Clear validation messages
- **API Errors**: Detailed error information from Ensembl
- **Network Issues**: Timeout and connectivity error handling
- **Species Validation**: Automatic species name validation

## Rate Limiting

The server respects Ensembl's rate limiting guidelines:

- Maximum 15 requests per second
- Appropriate delays between batch operations
- Connection pooling for efficiency

## Configuration

### Environment Variables

- `ENSEMBL_BASE_URL`: Override default API base URL
- `REQUEST_TIMEOUT`: Set custom timeout (default: 30000ms)

### Species Configuration

- Default species: `homo_sapiens`
- Automatic species validation
- Support for all Ensembl divisions

## API Coverage

This server provides access to major Ensembl REST API endpoints:

### Lookup & Search

- `/lookup/id/{id}` - Gene/transcript lookup
- `/search` - Gene search functionality

### Sequences

- `/sequence/id/{id}` - Feature sequences
- `/sequence/region/{species}/{region}` - Genomic sequences

### Comparative Genomics

- `/homology/id/{id}` - Homology data
- `/genetree/id/{id}` - Gene trees

### Variation

- `/variation/region/{species}/{region}` - Variant data
- `/vep/species/{species}/region` - Variant effect prediction

### Regulation

- `/regulatory/species/{species}/region/{region}` - Regulatory features
- `/regulatory/species/{species}/microarray/{region}` - Motif features

### Cross-references

- `/xrefs/id/{id}` - External database references
- `/map/coords/{species}/{assembly}/{region}` - Coordinate mapping

### Information

- `/info/species` - Available species
- `/info/assembly/{species}` - Assembly information

## Support

For issues related to:

- **Server functionality**: Check server logs and error messages
- **Ensembl data**: Refer to [Ensembl documentation](https://rest.ensembl.org/)
- **API usage**: See [Ensembl REST API guide](https://github.com/Ensembl/ensembl-rest/wiki)

## Contributing

Contributions are welcome! Please ensure:

- TypeScript compliance
- Comprehensive error handling
- Documentation updates
- Test coverage for new features

## Related Tools

This server integrates well with other bioinformatics MCP servers:

- **UniProt Server**: Protein data integration
- **AlphaFold Server**: 3D structure predictions
- **STRING Server**: Protein interaction networks
- **PDB Server**: Structural biology data

## About Augmented Nature

This Ensembl MCP Server is developed by [Augmented Nature](https://augmentednature.ai), a company focused on building AI-powered tools for scientific research and discovery.


## Citation
If you use this project in your research or publications, please cite it as follows:

```bibtex @misc{ensemblmcp2025, 
author = {Moudather Chelbi},
title = {Ensembl MCP Server},
year = {2025},
howpublished = {https://github.com/Augmented-Nature/Ensembl-MCP-Server},
note = {Accessed: 2025-06-29}