io.github.cyanheads/ensembl-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

Look up genes, sequences, variants, homologs, and cross-database xrefs from Ensembl REST.

io.github.cyanheads/ensembl-mcp-server (MCP Server)

The MCP server io.github.cyanheads/ensembl-mcp-server provides access to Ensembl REST for gene and sequence lookups. It can retrieve variants’ consequences, find orthologs (homologs), and return cross-database cross-references (xrefs). It runs over STDIO or Streamable HTTP and exposes 7 tools.

🛠️ Key Features

Look up genes
Fetch sequences
Predict variant consequences
Find orthologs / homologs
Retrieve cross-database xrefs from Ensembl REST

🚀 Use Cases

Gene and genomics research via Ensembl REST
Variant interpretation workflows using consequence prediction
Comparative analysis via ortholog/homolog retrieval
Integrating Ensembl-linked identifiers across databases (xrefs)

⚡ Developer Benefits

Model Context Protocol (MCP) server for tool access
Supports STDIO or Streamable HTTP transport
TypeScript-based tooling (topic-listed)

⚠️ Limitations

Functionality is bounded to Ensembl REST capabilities as stated in the description
Only 7 tools are provided (as indicated by tool count)

Topics

ai-agentsai-toolsbioinformaticscyanheadsensemblgenesgenomicsmcpmcp-servermodel-context-protocoltypescript

Captured live from the server via tools/list.

ensembl_list_species

List species supported by Ensembl with display name, common name, assembly, taxon ID, and division. Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects. Filter by division to select one; use nameContains to find a species by partial name match. With no division, returns the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint); pass a division to list that division.

Parameters2

division	string	optional	Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates).
nameContains	string	optional	Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: "sapiens" matches homo_sapiens; "mouse" matches mus_musculus.

Raw schema

{
  "type": "object",
  "properties": {
    "division": {
      "description": "Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates).",
      "type": "string",
      "enum": [
        "EnsemblVertebrates",
        "EnsemblPlants",
        "EnsemblFungi",
        "EnsemblMetazoa",
        "EnsemblProtists"
      ]
    },
    "nameContains": {
      "description": "Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: \"sapiens\" matches homo_sapiens; \"mouse\" matches mus_musculus.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_lookup_gene

Resolve a gene by symbol + species (or by stable ID) to its Ensembl ID, genomic location (chr:start-end:strand), biotype, description, and transcript list. Entry point for most workflows — the stable ID and coordinates returned here are inputs to other tools. Accepts both symbol lookup (BRCA2 + homo_sapiens) and direct ID lookup (ENSG00000139618). Supports batch lookup of up to 20 IDs or symbols in one call via the ids or symbols field. Provide exactly one of symbol, id, ids, or symbols. For symbol lookups species defaults to homo_sapiens (override for other organisms); for ID lookups species is not needed. Use ensembl_list_species to discover valid species names.

Parameters6

symbol	string	optional	Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species.
id	string	optional	Ensembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup.
species	string	optional	Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species to discover valid values.
ids	array	optional	Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols.
symbols	array	optional	Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols.
expand_transcripts	boolean	optional	When true, include the full transcript list in the response. Each transcript has its ID, biotype, canonical flag, and coordinates. Default is false to keep responses compact.

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "description": "Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species.",
      "type": "string"
    },
    "id": {
      "description": "Ensembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup.",
      "type": "string"
    },
    "species": {
      "description": "Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species to discover valid values.",
      "type": "string"
    },
    "ids": {
      "description": "Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "An Ensembl stable gene or transcript ID to resolve in this batch."
      }
    },
    "symbols": {
      "description": "Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "A gene symbol to resolve in this batch (e.g. BRCA2, TP53)."
      }
    },
    "expand_transcripts": {
      "default": false,
      "description": "When true, include the full transcript list in the response. Each transcript has its ID, biotype, canonical flag, and coordinates. Default is false to keep responses compact.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_get_sequence

Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region. Returns a window of the sequence — the first 10,000 characters by default — with its stable ID, molecule type, and full length. When more follows the window, truncated is true and nextOffset is the offset to request next; walking nextOffset reconstructs the whole sequence, and max_length 0 returns everything from offset to the end. The type parameter selects which sequence is fetched: genomic (default, includes introns), cdna (spliced transcript), cds (coding sequence only), protein. For region mode, set id to a region — either species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end with species set (e.g. id 13:32315086-32400268, species homo_sapiens), spanning at most 10,000,000 bases; regions return genomic DNA only. Protein sequences require a transcript or protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene with expand_transcripts=true to get the canonical transcript ID first.

Parameters7

id	string	required	Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases.
type	string	optional	Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID.
species	string	optional	Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region; optional for the species:chr:start-end form (the embedded species is used when the field is omitted). Optional for stable ID lookups — Ensembl infers species from the ID prefix.
expand_5prime	integer	optional	Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries.
expand_3prime	integer	optional	Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries.
offset	integer	optional	0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window.
max_length	integer	optional	Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases."
    },
    "type": {
      "default": "genomic",
      "description": "Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID.",
      "type": "string",
      "enum": [
        "genomic",
        "cdna",
        "cds",
        "protein"
      ]
    },
    "species": {
      "description": "Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region; optional for the species:chr:start-end form (the embedded species is used when the field is omitted). Optional for stable ID lookups — Ensembl infers species from the ID prefix.",
      "type": "string"
    },
    "expand_5prime": {
      "default": 0,
      "description": "Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand_3prime": {
      "default": 0,
      "description": "Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "offset": {
      "default": 0,
      "description": "0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_length": {
      "default": 10000,
      "description": "Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_query_region

Find genomic features overlapping a chromosomal region: genes, transcripts, variants, regulatory elements, or exons. Returns each feature with its stable ID, type, location, biotype, and name, plus the genome assembly the coordinates are on. Useful for "what's in this locus?" and for seeding follow-up lookups. Region format is chr:start-end (e.g. 13:32315086-32400268 for the BRCA2 locus), spanning at most 5,000,000 bases. Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. The feature parameter defaults to gene only — requesting variation in an 85 kb region matches 44,000+ entries. Explicitly include variation, regulatory, transcript, or exon only when needed. The response returns up to max_results features (default 100) while totalCount always reports the full count; set max_results to 0 for every feature, or query a smaller region to see a different slice. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.

Parameters5

species	string	required	Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Use ensembl_list_species to discover valid values.
region	string	required	Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results.
feature	array	optional	Feature types to retrieve — at least one. Default is gene only. Requesting variation in a large region can match tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller).
biotype	string	optional	Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Applied server-side by Ensembl. Not all feature types support biotype filtering.
max_results	integer	optional	Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap.

Raw schema

{
  "type": "object",
  "properties": {
    "species": {
      "type": "string",
      "minLength": 1,
      "description": "Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Use ensembl_list_species to discover valid values."
    },
    "region": {
      "type": "string",
      "minLength": 1,
      "description": "Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results."
    },
    "feature": {
      "default": [
        "gene"
      ],
      "description": "Feature types to retrieve — at least one. Default is gene only. Requesting variation in a large region can match tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller).",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "gene",
          "transcript",
          "variation",
          "regulatory",
          "exon"
        ],
        "description": "A feature type to retrieve: gene, transcript, variation, regulatory, or exon."
      }
    },
    "biotype": {
      "description": "Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Applied server-side by Ensembl. Not all feature types support biotype filtering.",
      "type": "string"
    },
    "max_results": {
      "default": 100,
      "description": "Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "species",
    "region"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_predict_variant

Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP). Accepts three input formats: HGVS notation (transcript-relative, e.g. ENST00000380152.8:c.2T>A, or genomic, e.g. 13:g.32316462T>A); region+allele (chr:start:end:strand/allele, e.g. 1:65568:65568:1/T); and a dbSNP rsID (e.g. rs334). Returns the most severe consequence term, affected transcripts and genes, impact level (HIGH/MODERATE/LOW/MODIFIER), and any colocated known variants with clinical significance. HGVS input: provide the full notation including transcript version for best results. Region+allele input: Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (a chr-prefixed name is also accepted). By default the response caps transcript consequences (max_transcript_consequences) and per-variant PubMed IDs (max_pubmed_ids_per_variant) to keep large VEP results compact — well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations. Truthful totals are always reported; set a cap to 0 (or include_all_colocated_pubmed=true) to retrieve the full set.

Parameters5

variant	string	required	Variant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the "chr" prefix, though a chr-prefixed name is also accepted.
species	string	optional	Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species to discover valid values.
max_transcript_consequences	integer	optional	Maximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count.
max_pubmed_ids_per_variant	integer	optional	Maximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true.
include_all_colocated_pubmed	boolean	optional	When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact.

Raw schema

{
  "type": "object",
  "properties": {
    "variant": {
      "type": "string",
      "minLength": 1,
      "description": "Variant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the \"chr\" prefix, though a chr-prefixed name is also accepted."
    },
    "species": {
      "default": "homo_sapiens",
      "description": "Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species to discover valid values.",
      "type": "string",
      "minLength": 1
    },
    "max_transcript_consequences": {
      "default": 10,
      "description": "Maximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_pubmed_ids_per_variant": {
      "default": 10,
      "description": "Maximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "include_all_colocated_pubmed": {
      "default": false,
      "description": "When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact.",
      "type": "boolean"
    }
  },
  "required": [
    "variant"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_get_homology

Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), perc_id (percent identity), perc_pos (percent positives), and taxonomy level. Essential for cross-species research — for example, "what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species or left open to return all available homologs.

Parameters6

symbol	string	optional	Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id.
id	string	optional	Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol.
species	string	optional	Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species to discover valid values.
target_species	string	optional	Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species to discover valid values.
type	string	optional	Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs.
max_results	integer	optional	Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap.

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "description": "Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id.",
      "type": "string"
    },
    "id": {
      "description": "Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol.",
      "type": "string"
    },
    "species": {
      "default": "homo_sapiens",
      "description": "Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species to discover valid values.",
      "type": "string",
      "minLength": 1
    },
    "target_species": {
      "description": "Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species to discover valid values.",
      "type": "string"
    },
    "type": {
      "default": "orthologues",
      "description": "Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs.",
      "type": "string",
      "enum": [
        "orthologues",
        "paralogues",
        "all"
      ]
    },
    "max_results": {
      "default": 25,
      "description": "Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

ensembl_get_xrefs

Retrieve cross-database references for a gene or feature — HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and others. Returns each xref with its database name, primary ID, display ID, and description. The dbname filter narrows to specific databases; omit to return all xrefs. IDs returned here chain to protein (pubchem via UniProt), literature (pubmed via PubMed IDs), disease (OMIM via MIM_GENE), and pathway (Reactome) resources. Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first. Common dbname values: HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA, RefSeq_peptide, Reactome, GO (Gene Ontology), ChEMBL.

Parameters2

id	string	required	Ensembl stable gene ID (ENSG…) or transcript ID (ENST…). Use ensembl_lookup_gene to get the stable ID from a gene symbol. xrefs/id returns the full cross-reference set (56+ entries for well-annotated genes like BRCA2).
dbname	string	optional	Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome (pathway IDs), GO (Gene Ontology terms). Omit to return all available xrefs.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Ensembl stable gene ID (ENSG…) or transcript ID (ENST…). Use ensembl_lookup_gene to get the stable ID from a gene symbol. xrefs/id returns the full cross-reference set (56+ entries for well-annotated genes like BRCA2)."
    },
    "dbname": {
      "description": "Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome (pathway IDs), GO (Gene Ontology terms). Omit to return all available xrefs.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md16 KBView on GitHub

@cyanheads/ensembl-mcp-server

Look up genes, fetch sequences, predict variant consequences, find orthologs, and retrieve cross-database xrefs from Ensembl REST via MCP. STDIO or Streamable HTTP.

7 Tools • 4 Resources • 1 Prompt

MCP SDK TypeScript

Public Hosted Server: https://ensembl.caseyjhand.com/mcp

Overview

Gene, sequence, and variant data for vertebrates and other model organisms from the Ensembl REST API. Look up genes, fetch sequences, predict variant consequences, find orthologs, and cross-reference external databases from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`ensembl_list_species`	List species supported by Ensembl with display name, common name, assembly, taxon ID, and division
`ensembl_lookup_gene`	Resolve a gene by symbol + species or by stable ID to its Ensembl ID, genomic location, biotype, and transcript list
`ensembl_get_sequence`	Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region
`ensembl_query_region`	Find genomic features (genes, transcripts, variants, regulatory elements, exons) overlapping a chromosomal region
`ensembl_predict_variant`	Predict functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP)
`ensembl_get_homology`	Find orthologs and/or paralogs of a gene across species with percent identity and taxonomy level
`ensembl_get_xrefs`	Retrieve cross-database references for a gene — HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and others

Resources

Resource	Description
`ensembl://gene/{id}`	Gene record by stable ID (`ENSG…`) — location, biotype, description, and transcript list
`ensembl://transcript/{id}`	Transcript record by stable ID (`ENST…`) — parent gene, location, biotype, canonical flag, and length
`ensembl://species`	Supported Ensembl species for the endpoint default division (vertebrates on the default endpoint)
`ensembl://species/{division}`	Supported species in one division (`EnsemblVertebrates`, `EnsemblPlants`, `EnsemblFungi`, `EnsemblMetazoa`, `EnsemblProtists`)

All resource data is also reachable via the ensembl_list_species tool, which additionally filters by name.

Prompts

Prompt	Description
`ensembl_gene_dossier`	Structured workflow for assembling a complete gene profile: symbol → ID + location → sequence → variants → orthologs → xrefs

Capability reference

`ensembl_list_species` _tool

Filter by division (EnsemblVertebrates, EnsemblPlants, EnsemblFungi, EnsemblMetazoa, EnsemblProtists) or nameContains for a local substring match against name, display name, and common name
Omit division to return the endpoint default division (vertebrates, ~356 species on the default GRCh38 endpoint)
Returns internal name (the value every other tool expects), display name, common name, taxon ID, assembly, and division
Required first step — species names like homo_sapiens are opaque to non-biologists

`ensembl_lookup_gene` _tool

Exactly one of symbol (+ optional species, default homo_sapiens), id, ids (batch, up to 20), or symbols (batch, up to 20)
expand_transcripts (default false) adds the full transcript list with biotype and canonical flag
Batch modes (ids/symbols) return a succeeded/failed split with per-item error strings instead of failing the call
Errors: not_found, invalid_species, no_input, conflicting_input

`ensembl_get_sequence` _tool

type: genomic (default, includes introns), cdna (spliced), cds (coding only), protein
Accepts a stable ID (ENSG…/ENST…/ENSP…) or a region — species:chr:start-end, or bare chr:start-end with species set; a region spans at most 10,000,000 bases, with start at or below end
expand_5prime / expand_3prime (default 0) extend flanking base pairs for genomic and region queries
protein and cds require a transcript or protein ID, not a gene ID; region ids are genomic-only
Returns a bounded window: offset (0-based, default 0) and max_length (default 10000, 0 for the rest uncapped) index the resolved sequence, flanks included
length is always the full sequence length; truncated and nextOffset say whether more follows and where to resume, so walking nextOffset reconstructs the whole sequence
Errors: not_found, type_mismatch, missing_species, invalid_region

`ensembl_query_region` _tool

region in chr:start-end format, at most 5,000,000 bases; feature array (at least one) defaults to ["gene"], also accepts transcript, variation, regulatory, exon; optional biotype filter
Defaults to genes only — requesting variation on a large locus can match 44,000+ features
max_results caps the feature list (default 100, 0 uncapped); totalCount always reports the true count found
assemblyName (e.g. GRCh38) names the assembly the coordinates are on
Exon rows carry a parentId and rank, since one exon is reported once per parent transcript
Errors: invalid_region, invalid_species

`ensembl_predict_variant` _tool

variant accepts HGVS (transcript-relative or genomic), region+allele (chr:start:end:strand/allele), or a dbSNP rsID
max_transcript_consequences (default 10) and max_pubmed_ids_per_variant (default 10) cap large VEP results; set either to 0 for the full set, or include_all_colocated_pubmed: true for uncapped PubMed IDs
Returns most severe consequence term, per-transcript impact (HIGH/MODERATE/LOW/MODIFIER), and colocated known variants with clinical significance
Totals (transcriptConsequencesTotal, pubmedTotal) are always reported even when capped
Errors: invalid_notation, not_found

`ensembl_get_homology` _tool

Exactly one of symbol (+ species, default homo_sapiens) or id; optional target_species filter
type: orthologues (default), paralogues, or all
max_results caps the homolog list (default 25, 0 uncapped); totalCount always reports the true count available
Errors: not_found, no_input, conflicting_input

`ensembl_get_xrefs` _tool

id (ENSG…/ENST…) required; optional dbname filter (e.g. HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA, Reactome, GO)
Uses the xrefs/id endpoint, returning the full cross-reference set (56+ entries for well-annotated genes like BRCA2)
Errors: not_found

`ensembl://gene/{id}` _resource

Returns location, biotype, description, and transcript list for a gene stable ID (ENSG…); version suffix optional
Errors: not_found

`ensembl://transcript/{id}` _resource

Returns parent gene, location, biotype, canonical flag, and length for a transcript stable ID (ENST…); version suffix optional
Errors: not_found

`ensembl://species` _resource

No parameters — returns the endpoint default division (vertebrates, ~356 species on the default GRCh38 endpoint)
For a named division, read ensembl://species/{division} instead

`ensembl://species/{division}` _resource

division required: EnsemblVertebrates, EnsemblPlants, EnsemblFungi, EnsemblMetazoa, or EnsemblProtists

`ensembl_gene_dossier` _prompt

Arguments: gene_symbol required; species optional (default homo_sapiens)
Sequences a 7-step workflow: resolve the gene → fetch the protein sequence → find variants in the locus → predict variant consequences → find cross-species orthologs → get external database IDs → synthesize the dossier

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Ensembl-specific:

Keyless REST API — no API key required; Ensembl REST is fully public at 55,000 req/hr
Rate-limit-aware service layer: retries 429 honoring Retry-After, and retries transient 5xx and HTML error pages
Batch POST endpoints used throughout — POST /lookup/id and POST /lookup/symbol/{species} (up to 1,000 items each upstream) reduce N+1 round trips in multi-gene workflows
GRCh37 legacy support via ENSEMBL_BASE_URL — point the entire server at https://grch37.rest.ensembl.org for clinical workflows on the older assembly
All coordinate-bearing responses echo the assembly name so agents never see a bare genomic position without assembly context

Agent-friendly output:

ensembl_get_sequence returns sequences in bounded windows (10,000 characters by default) with the full length and a nextOffset to continue, so a long gene or locus never lands in one response unasked
ensembl_list_species is explicitly the discovery step — tool descriptions call out the opaque internal-name format and direct agents to it before using species-dependent tools
Cross-tool chaining made explicit: xref IDs from ensembl_get_xrefs are described as inputs for protein and literature servers; the ensembl_gene_dossier prompt sequences all 6 tools into one research workflow

Getting started

Public Hosted Instance

A public instance is available at https://ensembl.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "streamable-http",
      "url": "https://ensembl.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/ensembl-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/ensembl-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/ensembl-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
No API key required — Ensembl REST is fully public.

Installation

Clone the repository:

git clone https://github.com/cyanheads/ensembl-mcp-server.git

Navigate into the directory:

cd ensembl-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env if you need to override ENSEMBL_BASE_URL (e.g. for GRCh37)

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

Variable	Description	Default
`ENSEMBL_BASE_URL`	Ensembl REST API base URL. Override for GRCh37 (`https://grch37.rest.ensembl.org`) or a local mirror.	`https://rest.ensembl.org`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path	`/mcp`
`MCP_SESSION_MODE`	HTTP session mode: `auto`, `stateful`, or `stateless`. Schema default `auto` resolves to stateful; this server explicitly uses stateless.	`stateless`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directory for log files (Node.js only)	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t ensembl-mcp-server .
docker run --rm -p 3010:3010 ensembl-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/ensembl-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources/prompts and inits services
`src/config`	Server-specific environment variable parsing and validation with Zod
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`) — 7 tools
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`) — gene, transcript, species
`src/mcp-server/prompts`	Prompt definitions (`*.prompt.ts`) — gene dossier workflow
`src/services/ensembl`	Ensembl REST API client — HTTP, rate-limit handling, retry, error normalization
`tests/`	Unit and integration tests mirroring `src/`

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools and resources in the createApp() arrays in src/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (7)

ensembl_list_speciesensembl_lookup_geneensembl_get_sequenceensembl_query_regionensembl_predict_variantensembl_get_homologyensembl_get_xrefs

Configuration

Environment variables

ENSEMBL_BASE_URLdefault https://rest.ensembl.org

Ensembl REST API base URL. Override to use GRCh37 endpoint or a local mirror.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/ensembl-mcp-server@0.5.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "ENSEMBL_BASE_URL": "https://rest.ensembl.org",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

io.github.cyanheads/ensembl-mcp-server (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

ensembl_list_species

ensembl_lookup_gene

ensembl_get_sequence

ensembl_query_region

ensembl_predict_variant

ensembl_get_homology

ensembl_get_xrefs

@cyanheads/ensembl-mcp-server

Overview

Tools

Resources

Prompts

Capability reference

ensembl_list_species tool

ensembl_lookup_gene tool

ensembl_get_sequence tool

ensembl_query_region tool

ensembl_predict_variant tool

ensembl_get_homology tool

ensembl_get_xrefs tool

ensembl://gene/{id} resource

ensembl://transcript/{id} resource

ensembl://species resource

ensembl://species/{division} resource

ensembl_gene_dossier prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`ensembl_list_species` _tool

`ensembl_lookup_gene` _tool

`ensembl_get_sequence` _tool

`ensembl_query_region` _tool

`ensembl_predict_variant` _tool

`ensembl_get_homology` _tool

`ensembl_get_xrefs` _tool

`ensembl://gene/{id}` _resource

`ensembl://transcript/{id}` _resource

`ensembl://species` _resource

`ensembl://species/{division}` _resource

`ensembl_gene_dossier` _prompt