Ensembl MCP Server

🚀 Unofficial Ensembl MCP Server

This is a comprehensive Model Context Protocol (MCP) server that provides access to the Ensembl REST API for genomic data, comparative genomics, and biological annotations. It enables users to interact with Ensembl's vast genomic database through a standardized MCP interface.

Developed by Augmented Nature

📚 Overview

This server allows seamless access to Ensembl's extensive genomic database via a standardized MCP interface. It supports a wide range of operations across multiple species, including gene lookups, sequence retrieval, variant analysis, comparative genomics, regulatory feature access, and more.

✨ Features

Gene & Transcript Information

• Gene Lookup: Obtain detailed gene information using an Ensembl ID or gene symbol.
• Transcript Analysis: Retrieve all transcripts for a gene along with their structural details.
• Gene Search: Search for genes by name, description, or identifier, with filtering options available.

Sequence Data

• Genomic Sequences: Extract DNA sequences for any genomic region or feature.
• CDS Sequences: Retrieve coding sequences for specific transcripts.
• Sequence Translation: Translate DNA sequences into protein sequences.
• Repeat Masking: Supports both hard and soft repeat masking.

Comparative Genomics

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

Variant Data

• Variant Retrieval: Fetch genetic variants in genomic regions.
• Consequence Prediction: Predict the effects of variants on genes and transcripts.
• Population Genetics: Access allele frequencies and population data.

Regulatory Features

• Regulatory Elements: Access data on enhancers, promoters, and transcription factor binding sites (TFBS).
• Motif Features: Retrieve transcription factor binding motifs.
• Cell Type Context: Filter regulatory features by cell type.

Cross-References & Annotations

• External Database Links: Obtain cross-references to databases such as PDB, EMBL, and RefSeq.
• Coordinate Mapping: Convert coordinates between different genome assemblies.
• Ontology Terms: Access Gene Ontology (GO) terms and functional annotations.

Species & Assembly Information

• Species Lists: Browse the available species and assemblies.
• Assembly Statistics: Get information and statistics about genome assemblies.
• Karyotype Data: Access chromosome information and banding patterns.

Batch Processing

• Batch Gene Lookup: Process multiple genes simultaneously.
• Batch Sequence Fetch: Efficiently retrieve sequences for multiple regions.

📦 Installation

# Clone or download the server files
cd ensembl-server

# Install dependencies
npm install

# Build the server
npm run build

💻 Usage Examples

Usage with Claude Desktop

Setup Instructions

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

npm run build

2. Add to Claude Desktop configuration:
   • Open Claude Desktop.
   • Navigate to Settings → MCP Servers.
   • Add a new server with the following details:
     • 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 - Retrieve detailed gene information using a stable ID or symbol.
• get_transcripts - Get all transcripts for a gene with detailed structural information.
• search_genes - Search for genes by name, description, or identifier.

Sequence Data

• get_sequence - Obtain DNA sequences for genomic coordinates or gene/transcript IDs.
• get_cds_sequence - Retrieve the coding sequence (CDS) for a transcript.
• translate_sequence - Translate a DNA sequence into a protein sequence.

Comparative Genomics

• get_homologs - Find orthologous and paralogous genes across different species.
• get_gene_tree - Obtain the phylogenetic tree for a gene family.

Variant Data

• get_variants - Fetch genetic variants in a genomic region.
• get_variant_consequences - Predict the effects of variants on genes and transcripts.

Regulatory Features

• get_regulatory_features - Access regulatory elements in a genomic region.
• get_motif_features - Retrieve transcription factor binding motifs in a genomic region.

Cross-References & Annotations

• get_xrefs - Obtain cross-references to external databases for genes.
• map_coordinates - Convert coordinates between different genome assemblies.

Species & Assembly Information

• list_species - Get a list of available species and assemblies.
• get_assembly_info - Obtain information and statistics about a genome assembly.
• get_karyotype - Access chromosome information and karyotype data.

Batch Processing

• batch_gene_lookup - Look up multiple genes simultaneously.
• batch_sequence_fetch - Retrieve sequences for multiple regions efficiently.

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. The default species is homo_sapiens if not specified.

📋 Input Formats

Genomic Regions

• chr1:1000000-2000000 - Standard format
• 1:1000000-2000000 - Without the '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 offers comprehensive error handling:

• Invalid Parameters: Clear validation messages are provided.
• API Errors: Detailed error information from Ensembl is presented.
• Network Issues: Timeout and connectivity errors are handled.
• Species Validation: Automatic species name validation is performed.

⏱️ Rate Limiting

The server adheres to Ensembl's rate limiting guidelines:

• A maximum of 15 requests per second is allowed.
• Appropriate delays are implemented between batch operations.
• Connection pooling is used for efficiency.

⚙️ Configuration

Environment Variables

• ENSEMBL_BASE_URL: Override the default API base URL.
• REQUEST_TIMEOUT: Set a custom timeout (default: 30000ms).

Species Configuration

• The default species is homo_sapiens.
• Automatic species validation is supported.
• All Ensembl divisions are supported.

📚 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 the server logs and error messages.
• Ensembl data: Refer to Ensembl documentation.
• API usage: See Ensembl REST API guide.

🤝 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, 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:

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