ensembl-mcp-server

Lookup Gene

ensembl_lookup_gene

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	No	Ensembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup.
`ids`	No	Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols.
`symbol`	No	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.
`species`	No	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.
`symbols`	No	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`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description
`gene`	No	Single gene record. Present for symbol or id lookups.
`batch`	No	Batch results. Present for ids or symbols lookups.
`error`	No	Present when the call failed. Absent on success.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 24, 2026
- addedInput schema / properties / ids / items / minLength
```
Added value: +1
```
- addedInput schema / properties / symbols / items / minLength
```
Added value: +1
```

Changed5 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    }
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "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.",
+          "examples": [
+            "not_found",
+            "invalid_species",
+            "no_input",
+            "conflicting_input"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedJun 22, 2026

changedInput schema / properties / ids / description

Previous value: -"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Cannot be combined with symbol or id."New value: +"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols."

changedInput schema / properties / species / description

Previous value: -"Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Required when using symbol. Default is homo_sapiens for symbol-based lookups. Use ensembl_list_species to discover valid values."New value: +"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."

changedInput schema / properties / symbol / description

Previous value: -"Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Requires species to be set. Case-insensitive in most species."New value: +"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."

changedInput schema / properties / symbols / description

Previous value: -"Batch lookup: up to 20 gene symbols. Requires species to be set. Returns a succeeded/failed split. Cannot be combined with symbol, id, or ids."New value: +"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."

First observedJun 7, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and open-world hints. The description adds useful behavioral detail beyond that: batch results split into succeeded/failed, species defaults, case-insensitivity, compact response behavior, and the one-of constraint. It does not belabor safety since annotations cover it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six sentences cover purpose, role in workflow, lookup modes, batch limit, one-of constraint, species defaults, and discovery route. Every sentence carries necessary information, and the structure front-loads the core purpose before edge-case guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with six parameters, multiple lookup modes, and an output schema, the description is complete: it explains when to use it, how to choose parameters, defaults, batch behavior, and where to find valid species names. The output schema covers return values, so no further description is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics: exactly one of the four lookup fields must be provided, species is only needed for symbol lookups, and ID lookups can skip species. These conditional relationships are not all fully captured by individual property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Resolve a gene... to its Ensembl ID, genomic location...'), lists concrete output fields, and positions itself as the entry point whose outputs feed other tools. This clearly distinguishes it from siblings like ensembl_get_sequence or ensembl_get_homology even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong situational context: entry point for most workflows, symbol vs ID lookup, batch mode, default species, and exactly-one-field rule. It stops short of explicitly saying when NOT to use it or naming alternate sibling tools for other tasks, so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ensembl-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.