ensembl-mcp-server
An MCP server that provides tools to query the Ensembl REST API for genomic data. It allows users to list species, look up genes by symbol or ID, fetch DNA/protein sequences, query genomic regions, predict variant consequences using VEP, find orthologs, and retrieve cross-database references.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://ensembl.caseyjhand.com/mcpWhat its tools do
7 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Look up gene details by symbol or stable ID
- Fetch DNA or protein sequences for genes
- Predict functional consequences of variants
- Find orthologs across species
Source and maintenance
Community listingRegistry 0.7.1
- Maintenance checked
Protocol and capabilities
- Server
- ensembl-mcp-server 0.7.1
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 7 advertised
- Resources
- 10 advertised
- Resource templates
- 4 advertised
- Prompts
- 1 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
7 advertised
ensembl_list_species — List Ensembl Species
Advertised read-onlyOpen-world
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. Use nameContains to find a species by partial name match; filter by division to select one. With no division, lists the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint). Species are sorted by internal name and returned max_results at a time (default 50); totalCount reports every match, and when more follow, nextOffset is the offset for the next page.
ensembl_list_species input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "0-based position in the name-sorted matches where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no species."
},
"division": {
"enum": [
"EnsemblVertebrates",
"EnsemblPlants",
"EnsemblFungi",
"EnsemblMetazoa",
"EnsemblProtists"
],
"type": "string",
"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)."
},
"max_results": {
"type": "integer",
"default": 50,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap."
},
"nameContains": {
"type": "string",
"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."
}
},
"additionalProperties": false
}ensembl_list_species output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"species",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The max_results limit applied to this page."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of species returned on this page."
},
"notice": {
"type": "string",
"description": "Guidance when the filter matches no species, the offset is past the end, or more species follow this page."
},
"species": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Ensembl internal species name in lowercase_underscore format (e.g. homo_sapiens, mus_musculus). This is the value to pass as the species parameter in all other Ensembl tools."
},
"taxonId": {
"type": "string",
"description": "NCBI taxonomy ID for this species."
},
"assembly": {
"type": "string",
"description": "Current genome assembly name (e.g. GRCh38)."
},
"division": {
"type": "string",
"description": "Ensembl division this species belongs to (e.g. EnsemblVertebrates, EnsemblPlants)."
},
"commonName": {
"type": "string",
"description": "Common name (e.g. Human, Mouse)."
},
"displayName": {
"type": "string",
"description": "Human-readable scientific name (e.g. Homo sapiens)."
}
},
"description": "A single Ensembl species entry.",
"additionalProperties": false
},
"description": "Species matching the filter criteria, sorted by internal name: at most max_results entries starting at offset."
},
"truncated": {
"type": "boolean",
"description": "True when more matching species follow this page; request nextOffset to continue."
},
"nextOffset": {
"type": "number",
"description": "Offset of the first species after this page — pass it as offset to fetch the next page. Present only when more species follow."
},
"totalCount": {
"type": "number",
"description": "Total number of matching species after local filtering, before offset and max_results. Exceeds the returned species count when the list was paged."
}
},
"additionalProperties": false
}ensembl_list_species annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_lookup_gene — Lookup Gene
Advertised read-onlyOpen-world
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). A symbol that is not a current gene name is matched against synonyms and former symbols (HER2 → ERBB2), reported as matchedAlias; when it maps to several genes the result is ambiguous, listing the candidates to retry by id. Supports batch submission of up to 1,000 IDs or symbols: the first 20 distinct queries are resolved, and batch.omitted names the unattempted remainder to resubmit. 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 with nameContains (a genus or common name) to find valid species names.
ensembl_lookup_gene input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"description": "Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix on an ENS… ID (ENSG00000139618.19) is dropped before the lookup, which returns the current version. Species is not required for ID lookup."
},
"ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "An Ensembl stable gene or transcript ID to resolve in this batch."
},
"maxItems": 1000,
"description": "Batch submission: up to 1,000 Ensembl stable IDs (ENSG…, ENST…); resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed/omitted partition; each attempted item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols."
},
"symbol": {
"type": "string",
"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. A synonym or former symbol (HER2, TB1) resolves too; one shared by several genes returns ambiguous with the candidates instead of gene."
},
"species": {
"type": "string",
"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 with nameContains (a genus or common name) to find valid values."
},
"symbols": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "A gene symbol to resolve in this batch (e.g. BRCA2, TP53)."
},
"maxItems": 1000,
"description": "Batch submission: up to 1,000 gene symbols; resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed/omitted partition; each attempted item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols."
},
"expand_transcripts": {
"type": "boolean",
"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."
}
},
"additionalProperties": false
}ensembl_lookup_gene output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"gene": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools."
},
"end": {
"type": "number",
"description": "Gene end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Gene start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene)."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup."
},
"chromosome": {
"type": "string",
"description": "Chromosome or sequence region name."
},
"description": {
"type": "string",
"description": "Brief gene description from Ensembl."
},
"displayName": {
"type": "string",
"description": "Gene symbol or display name (e.g. BRCA2, TP53)."
},
"transcripts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"isCanonical"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl transcript stable ID (ENST…)."
},
"end": {
"type": "number",
"description": "Transcript end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Transcript start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron)."
},
"lengthInBp": {
"type": "number",
"description": "Transcript length in base pairs."
},
"maneSelect": {
"type": "string",
"description": "MANE Select RefSeq transcript accession, when supplied by Ensembl."
},
"displayName": {
"type": "string",
"description": "Transcript display name."
},
"isCanonical": {
"type": "boolean",
"description": "True when this is the canonical transcript for the gene."
}
},
"description": "A single transcript summary entry.",
"additionalProperties": false
},
"description": "Transcript list. Present only when expand_transcripts is true."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly."
},
"matchedAlias": {
"type": "string",
"description": "The submitted symbol, present when it matched a synonym or former symbol rather than the current gene name; displayName holds the current name."
},
"parentGeneId": {
"type": "string",
"description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types."
},
"canonicalTranscript": {
"type": "string",
"description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence."
}
},
"description": "Single gene record. Present for an id lookup, or a symbol lookup that resolved to one gene.",
"additionalProperties": false
},
"batch": {
"type": "object",
"required": [
"omitted",
"succeeded",
"failed"
],
"properties": {
"failed": {
"type": "array",
"items": {
"type": "object",
"required": [
"query",
"reason",
"error",
"recovery"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong for this item."
},
"query": {
"type": "string",
"description": "The submitted ID or symbol."
},
"reason": {
"enum": [
"not_found",
"ambiguous",
"unavailable"
],
"type": "string",
"description": "not_found: nothing matched. ambiguous: the symbol is a synonym of several genes, listed in candidates. unavailable: Ensembl did not answer the synonym lookup for this symbol after retries, so whether it matches is unknown — retry it."
},
"recovery": {
"type": "string",
"description": "The next step for this item."
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools."
},
"end": {
"type": "number",
"description": "Gene end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Gene start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene)."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup."
},
"chromosome": {
"type": "string",
"description": "Chromosome or sequence region name."
},
"description": {
"type": "string",
"description": "Brief gene description from Ensembl."
},
"displayName": {
"type": "string",
"description": "Gene symbol or display name (e.g. BRCA2, TP53)."
},
"transcripts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"isCanonical"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl transcript stable ID (ENST…)."
},
"end": {
"type": "number",
"description": "Transcript end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Transcript start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron)."
},
"lengthInBp": {
"type": "number",
"description": "Transcript length in base pairs."
},
"maneSelect": {
"type": "string",
"description": "MANE Select RefSeq transcript accession, when supplied by Ensembl."
},
"displayName": {
"type": "string",
"description": "Transcript display name."
},
"isCanonical": {
"type": "boolean",
"description": "True when this is the canonical transcript for the gene."
}
},
"description": "A single transcript summary entry.",
"additionalProperties": false
},
"description": "Transcript list. Present only when expand_transcripts is true."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly."
},
"parentGeneId": {
"type": "string",
"description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types."
},
"canonicalTranscript": {
"type": "string",
"description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence."
}
},
"description": "A gene the symbol is a synonym or former symbol of.",
"additionalProperties": false
},
"description": "Every gene the symbol maps to. Present only when reason is ambiguous."
}
},
"description": "One unresolved ID or symbol.",
"additionalProperties": false
},
"description": "IDs/symbols that did not resolve to one gene, in input order."
},
"omitted": {
"type": "array",
"items": {
"type": "string",
"description": "A distinct submitted query not attempted in this call."
},
"description": "Queries past the first 20 distinct items, in first-occurrence order. Resubmit these separately."
},
"succeeded": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"query"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools."
},
"end": {
"type": "number",
"description": "Gene end position on the chromosome (1-based)."
},
"query": {
"type": "string",
"description": "The submitted ID or symbol this record resolved from."
},
"start": {
"type": "number",
"description": "Gene start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene)."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup."
},
"chromosome": {
"type": "string",
"description": "Chromosome or sequence region name."
},
"description": {
"type": "string",
"description": "Brief gene description from Ensembl."
},
"displayName": {
"type": "string",
"description": "Gene symbol or display name (e.g. BRCA2, TP53)."
},
"transcripts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"isCanonical"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl transcript stable ID (ENST…)."
},
"end": {
"type": "number",
"description": "Transcript end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Transcript start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron)."
},
"lengthInBp": {
"type": "number",
"description": "Transcript length in base pairs."
},
"maneSelect": {
"type": "string",
"description": "MANE Select RefSeq transcript accession, when supplied by Ensembl."
},
"displayName": {
"type": "string",
"description": "Transcript display name."
},
"isCanonical": {
"type": "boolean",
"description": "True when this is the canonical transcript for the gene."
}
},
"description": "A single transcript summary entry.",
"additionalProperties": false
},
"description": "Transcript list. Present only when expand_transcripts is true."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly."
},
"matchedAlias": {
"type": "string",
"description": "The submitted symbol, present when it matched a synonym or former symbol rather than the current gene name; displayName holds the current name."
},
"parentGeneId": {
"type": "string",
"description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types."
},
"canonicalTranscript": {
"type": "string",
"description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence."
}
},
"description": "A resolved gene record carrying its submitted query.",
"additionalProperties": false
},
"description": "Records for IDs/symbols that resolved to one gene, in input order."
}
},
"description": "Batch results. Present for ids or symbols lookups.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"not_found",
"invalid_species",
"no_input",
"conflicting_input"
],
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl. `invalid_species`: The species string was not recognized by Ensembl. `no_input`: Neither symbol, id, ids, nor symbols was provided. `conflicting_input`: More than one of symbol, id, ids, or symbols was provided. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance for resubmitting unattempted batch queries."
},
"ambiguous": {
"type": "object",
"required": [
"query",
"candidates",
"guidance"
],
"properties": {
"query": {
"type": "string",
"description": "The submitted symbol."
},
"guidance": {
"type": "string",
"description": "How to pick a candidate and retry by id."
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools."
},
"end": {
"type": "number",
"description": "Gene end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Gene start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene)."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup."
},
"chromosome": {
"type": "string",
"description": "Chromosome or sequence region name."
},
"description": {
"type": "string",
"description": "Brief gene description from Ensembl."
},
"displayName": {
"type": "string",
"description": "Gene symbol or display name (e.g. BRCA2, TP53)."
},
"transcripts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"isCanonical"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl transcript stable ID (ENST…)."
},
"end": {
"type": "number",
"description": "Transcript end position on the chromosome (1-based)."
},
"start": {
"type": "number",
"description": "Transcript start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron)."
},
"lengthInBp": {
"type": "number",
"description": "Transcript length in base pairs."
},
"maneSelect": {
"type": "string",
"description": "MANE Select RefSeq transcript accession, when supplied by Ensembl."
},
"displayName": {
"type": "string",
"description": "Transcript display name."
},
"isCanonical": {
"type": "boolean",
"description": "True when this is the canonical transcript for the gene."
}
},
"description": "A single transcript summary entry.",
"additionalProperties": false
},
"description": "Transcript list. Present only when expand_transcripts is true."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly."
},
"parentGeneId": {
"type": "string",
"description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types."
},
"canonicalTranscript": {
"type": "string",
"description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence."
}
},
"description": "A gene the symbol is a synonym or former symbol of.",
"additionalProperties": false
},
"description": "Every gene the symbol maps to. Retry with id set to the intended one."
}
},
"description": "Present instead of gene when a symbol is not a current gene name and is a synonym or former symbol of several genes.",
"additionalProperties": false
}
},
"additionalProperties": false
}ensembl_lookup_gene annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_get_sequence — Get Sequence
Advertised read-onlyOpen-world
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; a :-1 suffix (13:32315086-32315100:-1) returns the reverse-strand sequence. Regions return genomic DNA only. Protein sequences require a transcript or protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene and its canonicalTranscript field first; expand_transcripts=true also supplies transcript biotypes and MANE Select accessions.
ensembl_get_sequence input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode — an id containing a colon is a region. A version suffix on a stable ID (ENST00000380152.8) is dropped before the request. 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. Coordinates are whole numbers; start..end works as well as start-end, and a :1 or :-1 suffix picks the strand (13:32315086-32315100:-1 returns the reverse complement). A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases. Name chromosomes as Ensembl does (13, X, MT; chr13 also works); the mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans. M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one); elsewhere they fail as invalid_region naming the mitochondrion of the species."
},
"type": {
"enum": [
"genomic",
"cdna",
"cds",
"protein"
],
"type": "string",
"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. A protein ID (ENSP…) serves only its protein; a non-coding transcript has no protein or cds."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 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."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region. For the species:chr:start-end form the species in id takes precedence and this field is ignored. Unused for stable ID lookups — Ensembl infers species from the ID prefix."
},
"max_length": {
"type": "integer",
"default": 10000,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped."
},
"expand_3prime": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 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; on a :-1 region it extends the lower coordinate."
},
"expand_5prime": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 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; on a :-1 region it extends the higher coordinate."
}
},
"additionalProperties": false
}ensembl_get_sequence output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"id",
"type",
"seq",
"length",
"offset",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"description": "The stable ID or region used for the lookup."
},
"seq": {
"type": "string",
"description": "The requested window of the sequence: at most max_length characters starting at offset. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes); protein sequences use single-letter amino acid codes. Empty when offset is at or past the end."
},
"type": {
"type": "string",
"description": "Sequence type returned (genomic, cdna, cds, or protein)."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"not_found",
"type_mismatch",
"invalid_species",
"missing_species",
"invalid_region"
],
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: The requested type does not exist for the id: cdna, cds, or protein for a region id or a gene ID; genomic, cdna, or cds for a protein ID; or protein or cds for a non-coding transcript. `invalid_species`: The species of a region (the species field or the species prefix in id) was not recognized by Ensembl. `missing_species`: A bare chr:start-end region was given without a species. `invalid_region`: A region id is not in the [species:]chr:start-end form, has its start after its end, starts past the end of its sequence region, spans more than the 10,000,000-base maximum, names the mitochondrion M or chrM where Ensembl resolves that to another region or none, or names a sequence region the species lacks. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"length": {
"type": "number",
"description": "Full sequence length in characters, not the window size — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Includes any expand_5prime/expand_3prime flank."
},
"notice": {
"type": "string",
"description": "Guidance about the window: how to continue when truncated, or why it is empty when the offset is past the end."
},
"offset": {
"type": "number",
"description": "0-based character offset where this window starts."
},
"truncated": {
"type": "boolean",
"description": "True when more sequence follows this window; request nextOffset to continue."
},
"nextOffset": {
"type": "number",
"description": "Offset of the first character after this window — pass it as offset to fetch the next window. Present only when truncated."
},
"description": {
"type": "string",
"description": "Sequence description from Ensembl, if provided."
}
},
"additionalProperties": false
}ensembl_get_sequence annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_query_region — Query Genomic Region
Advertised read-onlyOpen-world
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 with species set (e.g. 13:32315086-32400268 for the BRCA2 locus), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), 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.
ensembl_query_region input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"region"
],
"properties": {
"region": {
"type": "string",
"minLength": 1,
"description": "Genomic region as chr:start-end with species set (e.g. 13:32315086-32400268), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), with start at or below end. 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. The mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans; M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one) and otherwise fail as invalid_region naming the mitochondrion of the species. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results."
},
"biotype": {
"type": "string",
"description": "Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Case-sensitive (lncRNA, not lncrna); remove the filter to inspect all matching feature types. Applied server-side by Ensembl. Not all feature types support biotype filtering."
},
"feature": {
"type": "array",
"items": {
"enum": [
"gene",
"transcript",
"variation",
"regulatory",
"exon"
],
"type": "string",
"description": "A feature type to retrieve: gene, transcript, variation, regulatory, or exon."
},
"default": [
"gene"
],
"minItems": 1,
"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)."
},
"species": {
"type": "string",
"minLength": 1,
"description": "Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Required for a bare chr:start-end region; for the species:chr:start-end form the species in region takes precedence and this field is ignored. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values."
},
"max_results": {
"type": "integer",
"default": 100,
"maximum": 9007199254740991,
"minimum": 0,
"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."
}
},
"additionalProperties": false
}ensembl_query_region output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"features",
"totalCount",
"region",
"species"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The max_results limit applied to the feature list."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_region",
"invalid_species",
"missing_species"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed, has its start greater than its end, names the mitochondrion M or chrM where Ensembl resolves that to another region or none, contains coordinates outside the sequence region, or spans more than the 5,000,000-base maximum. `invalid_species`: The species (the species field or the region's species prefix) was not recognized by Ensembl. `missing_species`: A bare chr:start-end region was given without a species. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of features returned after the max_results cap."
},
"notice": {
"type": "string",
"description": "Guidance about the result set: empty, large, capped, or missing assembly."
},
"region": {
"type": "string",
"description": "The region queried, as provided minus any species prefix (reported as species)."
},
"species": {
"type": "string",
"description": "The species queried: the region's species prefix when it has one, otherwise the species field."
},
"features": {
"type": "array",
"items": {
"type": "object",
"required": [
"featureType",
"chromosome",
"start",
"end"
],
"properties": {
"id": {
"type": "string",
"description": "Ensembl stable ID for this feature (e.g. ENSG…, rs…)."
},
"end": {
"type": "number",
"description": "End position on the chromosome (1-based)."
},
"name": {
"type": "string",
"description": "External name or symbol for this feature."
},
"rank": {
"type": "number",
"description": "Position (1-based) of an exon within its parent transcript."
},
"start": {
"type": "number",
"description": "Start position on the chromosome (1-based)."
},
"strand": {
"type": "number",
"description": "Strand: 1 for forward, -1 for reverse."
},
"biotype": {
"type": "string",
"description": "Biotype of the feature (e.g. protein_coding, lncRNA, SNV)."
},
"parentId": {
"type": "string",
"description": "Parent transcript ID (ENST…) for exon features. An exon is reported once per parent transcript it belongs to, so the same exon ID can appear on multiple rows that differ only by this field — not duplicates."
},
"chromosome": {
"type": "string",
"description": "Chromosome or sequence region name."
},
"description": {
"type": "string",
"description": "Feature description when provided."
},
"featureType": {
"type": "string",
"description": "Feature type: gene, transcript, variation, regulatory, or exon."
},
"consequenceType": {
"type": "string",
"description": "Most severe consequence type for variation features."
},
"clinicalSignificance": {
"type": "array",
"items": {
"type": "string",
"description": "A clinical significance term for this variant."
},
"description": "Clinical significance terms for variation features (e.g. pathogenic, benign)."
}
},
"description": "A single genomic feature overlapping the queried region.",
"additionalProperties": false
},
"description": "Genomic features found in the requested region, capped to max_results. totalCount reports the full count found before the cap."
},
"truncated": {
"type": "boolean",
"description": "True when the feature list was capped at max_results."
},
"totalCount": {
"type": "number",
"description": "Total number of features found in the region before the max_results cap. Exceeds the returned features count when the list was capped."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly the coordinates are on (e.g. GRCh38). Omitted only when it could not be resolved, in which case the notice says so."
}
},
"additionalProperties": false
}ensembl_query_region annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_predict_variant — Predict Variant Effect
Advertised read-onlyOpen-world
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.
ensembl_predict_variant input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"variant"
],
"properties": {
"species": {
"type": "string",
"default": "homo_sapiens",
"minLength": 1,
"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 with nameContains (a genus or common name) to find valid values."
},
"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."
},
"max_pubmed_ids_per_variant": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 0,
"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."
},
"max_transcript_consequences": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 0,
"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."
},
"include_all_colocated_pubmed": {
"type": "boolean",
"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."
}
},
"additionalProperties": false
}ensembl_predict_variant output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The max_transcript_consequences limit applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_notation",
"not_found",
"invalid_species"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_notation`: The variant notation is malformed or cannot be parsed by VEP. `not_found`: The variant location falls outside any known transcript or assembly region. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Total transcript consequences returned across all records after the cap."
},
"notice": {
"type": "string",
"description": "Guidance when no results are returned or when caps omitted detail."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"transcriptConsequences",
"colocatedVariants"
],
"properties": {
"end": {
"type": "number",
"description": "Variant end position (1-based)."
},
"input": {
"type": "string",
"description": "The input variant notation as submitted to VEP."
},
"start": {
"type": "number",
"description": "Variant start position (1-based)."
},
"chromosome": {
"type": "string",
"description": "Chromosome the variant is on."
},
"alleleString": {
"type": "string",
"description": "Reference and alternate alleles returned by VEP, separated by slashes."
},
"assemblyName": {
"type": "string",
"description": "Genome assembly name (e.g. GRCh38)."
},
"colocatedVariants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Known variant ID (e.g. rs1234567 for dbSNP entries)."
},
"pubmed": {
"type": "array",
"items": {
"type": "number",
"description": "A PubMed ID for literature citing this variant."
},
"description": "PubMed IDs for literature associated with this variant, capped to max_pubmed_ids_per_variant. pubmedTotal reports the full count when the list was capped."
},
"pubmedTotal": {
"type": "number",
"description": "Total PubMed IDs available for this variant before the max_pubmed_ids_per_variant cap. Equals the returned pubmed length when the list was not capped."
},
"alleleString": {
"type": "string",
"description": "Allele string showing reference/alternate (e.g. A/T)."
},
"clinicalSignificance": {
"type": "array",
"items": {
"type": "string",
"description": "A clinical significance term for this colocated known variant."
},
"description": "Aggregate clinical significance terms for the colocated record; these do not classify the submitted allele."
},
"clinicalSignificanceByAllele": {
"type": "object",
"description": "Clinical significance terms keyed by the allele explicitly annotated in the colocated record. Missing alleles have no reported attribution.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"clinicalSignificanceReferenceAllele": {
"type": "string",
"description": "Reference allele for the colocated clinical annotations, when reported."
}
},
"description": "A known variant at the same genomic position from public databases (dbSNP, ClinVar).",
"additionalProperties": false
},
"description": "Known variants at the same position from public databases (dbSNP, ClinVar). Empty when the variant is novel."
},
"mostSevereConsequence": {
"type": "string",
"description": "Most severe Sequence Ontology consequence term across all transcripts (e.g. stop_gained, missense_variant, synonymous_variant)."
},
"transcriptConsequences": {
"type": "array",
"items": {
"type": "object",
"required": [
"consequenceTerms"
],
"properties": {
"sift": {
"type": "object",
"required": [
"prediction",
"score"
],
"properties": {
"score": {
"type": "number",
"description": "SIFT score (0-1). Lower scores indicate more deleterious variants."
},
"prediction": {
"type": "string",
"description": "SIFT prediction: deleterious or tolerated."
}
},
"description": "SIFT pathogenicity prediction for missense variants. Omitted when not applicable.",
"additionalProperties": false
},
"hgvsc": {
"type": "string",
"description": "HGVS notation at the cDNA level (e.g. c.2T>A)."
},
"hgvsp": {
"type": "string",
"description": "HGVS notation at the protein level (e.g. p.Met1Thr)."
},
"geneId": {
"type": "string",
"description": "Ensembl gene ID (ENSG…) harboring the affected transcript."
},
"impact": {
"type": "string",
"description": "Impact level: HIGH (frameshift, stop_gained), MODERATE (missense), LOW (synonymous), or MODIFIER."
},
"biotype": {
"type": "string",
"description": "Transcript biotype (e.g. protein_coding)."
},
"polyphen": {
"type": "object",
"required": [
"prediction",
"score"
],
"properties": {
"score": {
"type": "number",
"description": "PolyPhen score (0-1). Higher scores indicate more damaging variants."
},
"prediction": {
"type": "string",
"description": "PolyPhen prediction: probably_damaging, possibly_damaging, or benign."
}
},
"description": "PolyPhen pathogenicity prediction for missense variants. Omitted when not applicable.",
"additionalProperties": false
},
"canonical": {
"type": "boolean",
"description": "Whether Ensembl marks this consequence transcript as canonical. Omitted when not reported."
},
"aminoAcids": {
"type": "string",
"description": "Reference/alternate amino acids separated by \"/\" (e.g. M/T)."
},
"geneSymbol": {
"type": "string",
"description": "Gene symbol (e.g. BRCA2, TP53)."
},
"maneSelect": {
"type": "string",
"description": "MANE Select RefSeq transcript accession, when supplied."
},
"transcriptId": {
"type": "string",
"description": "Ensembl transcript ID (ENST…) affected by this variant."
},
"variantAllele": {
"type": "string",
"description": "Allele this transcript consequence describes, in the upstream genomic orientation."
},
"consequenceTerms": {
"type": "array",
"items": {
"type": "string",
"description": "A Sequence Ontology consequence term (e.g. missense_variant, stop_gained)."
},
"description": "Sequence Ontology consequence terms for this transcript."
}
},
"description": "Consequence details for one affected transcript, including impact, HGVS notation, and pathogenicity scores.",
"additionalProperties": false
},
"description": "Per-transcript consequence details, capped to max_transcript_consequences. High-impact variants may affect many transcripts; canonical and maneSelect identify annotated primary transcripts. transcriptConsequencesTotal reports the full count."
},
"transcriptConsequencesTotal": {
"type": "number",
"description": "Total transcript consequences available before the max_transcript_consequences cap. Equals the returned transcriptConsequences length when not capped."
}
},
"description": "VEP consequence record for one genomic position, with transcript consequences and colocated known variants.",
"additionalProperties": false
},
"description": "VEP consequence records — typically one per input variant. Multiple records appear when a single notation matches multiple genomic positions."
},
"truncated": {
"type": "boolean",
"description": "True when transcript consequences were capped at max_transcript_consequences."
},
"totalCount": {
"type": "number",
"description": "Number of VEP consequence records returned."
}
},
"additionalProperties": false
}ensembl_predict_variant annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_get_homology — Get Gene Homologs
Advertised read-onlyOpen-world
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.), percId and percPos (percent identical and positive positions, over the target protein's length), 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. A target_species outside the comparison Ensembl runs for the source species is answered from Ensembl's pan-taxonomic comparison when that comparison holds both species. Includes targetProteinId when available for ensembl_get_sequence with type="protein". targetSymbol is best-effort: a secondary gene lookup shares five seconds across the returned rows and the remaining call deadline; missing names never remove homologs.
ensembl_get_homology input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"description": "Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol."
},
"type": {
"enum": [
"orthologues",
"paralogues",
"all"
],
"type": "string",
"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."
},
"symbol": {
"type": "string",
"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."
},
"species": {
"type": "string",
"default": "homo_sapiens",
"minLength": 1,
"description": "Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values."
},
"max_results": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 0,
"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."
},
"target_species": {
"type": "string",
"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 with nameContains (a genus or common name) to find valid values."
}
},
"additionalProperties": false
}ensembl_get_homology output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"homologs",
"totalCount",
"queryId",
"querySpecies",
"queryType"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The max_results limit applied to the homolog list."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"not_found",
"invalid_species",
"target_not_compared",
"no_input",
"conflicting_input"
],
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl for the source species. `invalid_species`: The species or target_species string was not recognized by Ensembl. `target_not_compared`: Both species are valid, but target_species is outside the comparison Ensembl runs for the source species, and Ensembl's pan-taxonomic comparison does not hold both species or its species list could not be read. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of homologs returned after the max_results cap."
},
"notice": {
"type": "string",
"description": "Guidance when the homologs come from Ensembl's pan-taxonomic comparison, no homologs are found, the list was capped, or symbol enrichment is incomplete."
},
"queryId": {
"type": "string",
"description": "The resolved Ensembl gene ID used for the homology query."
},
"homologs": {
"type": "array",
"items": {
"type": "object",
"required": [
"targetId"
],
"properties": {
"type": {
"type": "string",
"description": "Homology type: ortholog_one2one, ortholog_one2many, ortholog_many2many, paralog_many2many, within_species_paralog, or similar."
},
"percId": {
"type": "number",
"description": "Percent identity over the target protein's length (0-100): identical positions divided by the target protein's length. The query-side value differs when the two proteins differ in length."
},
"percPos": {
"type": "number",
"description": "Percent positive positions over the target protein's length (0-100): identical residues plus conservative substitutions, divided by the target protein's length."
},
"targetId": {
"type": "string",
"description": "Ensembl stable ID of the homologous gene in the target species."
},
"targetSymbol": {
"type": "string",
"description": "Target gene display name, when a bounded secondary lookup resolves it."
},
"targetSpecies": {
"type": "string",
"description": "Target species in Ensembl internal format (e.g. mus_musculus)."
},
"taxonomyLevel": {
"type": "string",
"description": "Last common ancestor taxonomic level for this homology relationship (e.g. Amniota, Vertebrata, Bilateria)."
},
"targetProteinId": {
"type": "string",
"description": "Target translation stable ID. Pass to ensembl_get_sequence with type=\"protein\"."
}
},
"description": "A single homologous gene with its stable ID, species, homology type, and sequence identity metrics.",
"additionalProperties": false
},
"description": "Homologous genes found for the query gene, capped to max_results. totalCount reports the full count available before the cap."
},
"queryType": {
"type": "string",
"description": "The homology type queried (orthologues, paralogues, or all)."
},
"truncated": {
"type": "boolean",
"description": "True when the homolog list was capped at max_results."
},
"totalCount": {
"type": "number",
"description": "Total number of homologs available before the max_results cap. Exceeds the returned homologs count when the list was capped."
},
"querySpecies": {
"type": "string",
"description": "The source species used for the query."
}
},
"additionalProperties": false
}ensembl_get_homology annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ensembl_get_xrefs — Get Cross-Database References
Advertised read-onlyOpen-world
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, plus how Ensembl assigned it (infoType, infoText) and its evidence codes (linkageTypes, such as GO evidence codes) when supplied. By default only the requested object level is queried; all_levels=true includes transcript and translation references for a gene. The dbname filter narrows this scope. IDs returned here chain onward: a Uniprot/SWISSPROT accession to UniProt (protein function) and PubChem (bioassays against the protein), MIM_GENE to OMIM (disease), Reactome_gene and Reactome to Reactome (pathways), and PDB to structure sources. Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first. Common dbname values: HGNC, Uniprot_gn, Uniprot/SWISSPROT (reviewed UniProt accession, held on the translation: use all_levels=true from a gene or transcript), EntrezGene, MIM_GENE, RefSeq_mRNA, RefSeq_peptide, Reactome_gene (gene pathways), Reactome (translation pathways), GO (Gene Ontology), ChEMBL.
ensembl_get_xrefs input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Ensembl stable gene (ENSG…), transcript (ENST…), or translation (ENSP…) ID. A version suffix on an ENS… ID (ENSG00000139618.17) is dropped before the request. Use ensembl_lookup_gene to get the stable ID from a gene symbol. References default to this object level; all_levels=true includes child objects."
},
"dbname": {
"type": "string",
"description": "Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), Uniprot/SWISSPROT (reviewed UniProt accession, on the translation), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome_gene (gene pathways), Reactome (translation pathways), GO (Gene Ontology terms). Transcript/translation references may require all_levels=true or the specific feature ID. Omit to return every database within the selected scope."
},
"all_levels": {
"type": "boolean",
"default": false,
"description": "Include references on child objects: a gene includes its transcripts and translations. Default false queries only the requested object level, independently of dbname."
}
},
"additionalProperties": false
}ensembl_get_xrefs output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"xrefs",
"totalCount",
"queriedId"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"not_found"
],
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: The Ensembl stable ID was not found. An empty cross-reference list remains successful. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"xrefs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dbname": {
"type": "string",
"description": "Database name in Ensembl internal format (e.g. HGNC, Uniprot_gn, Uniprot/SWISSPROT, EntrezGene, MIM_GENE, RefSeq_mRNA)."
},
"infoText": {
"type": "string",
"description": "Detail Ensembl records for the assignment: its source (e.g. UniProt, GO_Central) or, for a projection, the ortholog it came from. Omitted when blank."
},
"infoType": {
"type": "string",
"description": "How Ensembl assigned the reference, e.g. DIRECT (from the external database), DEPENDENT (derived from another reference), PROJECTION (projected from an ortholog), SEQUENCE_MATCH, CHECKSUM."
},
"displayId": {
"type": "string",
"description": "Display identifier — often the same as primaryId but may be a formatted accession."
},
"primaryId": {
"type": "string",
"description": "Primary identifier in the external database (e.g. HGNC:1101 for BRCA2 in HGNC, P51587 for BRCA2 in UniProt)."
},
"description": {
"type": "string",
"description": "Description of the cross-reference entry."
},
"linkageTypes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Evidence codes supporting the reference — GO evidence codes on GO terms (e.g. IDA experimental, IEA electronic, ISS sequence similarity). Omitted when Ensembl lists none."
},
"dbDisplayName": {
"type": "string",
"description": "Human-readable database display name."
}
},
"description": "A single cross-database reference entry with database name, primary ID, and description.",
"additionalProperties": false
},
"description": "Cross-database references for the queried Ensembl ID."
},
"notice": {
"type": "string",
"description": "Guidance when no cross-references are found."
},
"queriedId": {
"type": "string",
"description": "The Ensembl stable ID as submitted, including any version suffix."
},
"totalCount": {
"type": "number",
"description": "Total number of cross-references returned."
}
},
"additionalProperties": false
}ensembl_get_xrefs annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}Prompts
1 advertised
ensembl_gene_dossier
Structured research workflow for assembling a complete gene profile. Guides the agent through the Ensembl tool chain in order: symbol → ID + location → protein sequence → key variants → model-organism orthologs → external database IDs for protein and disease follow-up.
- gene_symbol
- Gene symbol to research (e.g. BRCA2, TP53, EGFR). Case-insensitive; Ensembl will resolve the canonical form. (required)
- species
- Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Default is homo_sapiens. Use ensembl_list_species with nameContains (e.g. "mouse") to find a valid value.
Resources
10 advertised
Ensembl Species — Ensembl Species
Ensembl species catalog for the endpoint default division — internal name, display name, assembly, taxon ID, and division. On the default GRCh38 endpoint this is the vertebrate division (~356 species). Returns the first 50 species by internal name with totalCount, shown, and truncated; when truncated, a notice points to the ensembl_list_species tool (offset, max_results) for the rest. For a specific division read ensembl://species/{division} (e.g. ensembl://species/EnsemblPlants); the tool also filters by name.
Ensembl Species URI
ensembl://speciesBRCA2 (homo_sapiens) — Ensembl Gene
Example: BRCA2 breast cancer susceptibility gene
BRCA2 (homo_sapiens) URI
ensembl://gene/ENSG00000139618TP53 (homo_sapiens) — Ensembl Gene
Example: Tumor protein p53
TP53 (homo_sapiens) URI
ensembl://gene/ENSG00000141510BRCA2-201 canonical transcript (homo_sapiens) — Ensembl Transcript
Example: canonical BRCA2 transcript
BRCA2-201 canonical transcript (homo_sapiens) URI
ensembl://transcript/ENST00000380152EnsemblVertebrates species — Ensembl Species by Division
Ensembl-supported species in the EnsemblVertebrates division
EnsemblVertebrates species URI
ensembl://species/EnsemblVertebratesEnsemblPlants species — Ensembl Species by Division
Ensembl-supported species in the EnsemblPlants division
EnsemblPlants species URI
ensembl://species/EnsemblPlantsEnsemblFungi species — Ensembl Species by Division
Ensembl-supported species in the EnsemblFungi division
EnsemblFungi species URI
ensembl://species/EnsemblFungiEnsemblMetazoa species — Ensembl Species by Division
Ensembl-supported species in the EnsemblMetazoa division
EnsemblMetazoa species URI
ensembl://species/EnsemblMetazoaEnsemblProtists species — Ensembl Species by Division
Ensembl-supported species in the EnsemblProtists division
EnsemblProtists species URI
ensembl://species/EnsemblProtistsensembl-guide
Gates and identifier chains for the ensembl_* tools. Covers checking a coordinate's assembly before you pass it in, finding a gene's counterpart in another species through homology, reading multi-allelic and capped VEP results, and which Ensembl object holds the UniProt, RefSeq, GO, and PDB references. Use when an ensembl_* result feeds a conclusion about a gene, variant, ortholog, or external ID.
ensembl-guide URI
skill://ensembl-guide/SKILL.mdEnsembl Gene — Ensembl Gene
Gene record by Ensembl stable ID (ENSG…). Returns location, biotype, description, canonicalTranscript, and a transcript list with MANE Select accessions when available. Stable, injectable context for multi-step workflows. Use ensembl_lookup_gene to resolve a gene symbol to the stable ID first.
Ensembl Gene URI template
ensembl://gene/{id}Ensembl Transcript — Ensembl Transcript
Transcript record by Ensembl stable ID (ENST…). Returns parent gene, location, biotype, canonical flag, and length. Use canonicalTranscript from ensembl_lookup_gene, or expand_transcripts=true for all transcript IDs and MANE Select accessions, then fetch this resource for stable, injectable context.
Ensembl Transcript URI template
ensembl://transcript/{id}Ensembl Species by Division — Ensembl Species by Division
Ensembl-supported species within a single division (EnsemblVertebrates, EnsemblPlants, EnsemblFungi, EnsemblMetazoa, or EnsemblProtists) — internal name, display name, assembly, taxon ID, and division. Returns the first 50 species by internal name with totalCount, shown, and truncated; when truncated, a notice points to the ensembl_list_species tool (division, offset, max_results) for the rest. Read ensembl://species for the endpoint default division (vertebrates); the tool also filters by name.
Ensembl Species by Division URI template
ensembl://species/{division}io.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
- 2026-11-09: 2 of 2 checks answered
- 2026-11-10: 2 of 2 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 900 ms
- 95th percentile latency
- 900 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 900 ms · metadata changed · 7 tool(s), 10 resource(s), 4 resource template(s), 1 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http ensembl-mcp-server-caseyjhand https://ensembl.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add ensembl-mcp-server-caseyjhand --url https://ensembl.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"ensembl-mcp-server-caseyjhand": {
"url": "https://ensembl.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"ensembl-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://ensembl.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"ensembl-mcp-server-caseyjhand": {
"type": "http",
"url": "https://ensembl.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http ensembl-mcp-server-caseyjhand https://ensembl.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://ensembl.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"ensembl-mcp-server-caseyjhand": {
"serverUrl": "https://ensembl.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like ensembl-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.