Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:489-498 (handler)

  The handleLookup function serves as the primary handler for the 'ensembl_lookup' tool. It normalizes the input arguments and delegates execution to the EnsemblApiClient's performLookup method.
  export async function handleLookup(args: any) { try { const normalizedArgs = normalizeEnsemblInputs(args); return await ensemblClient.performLookup(normalizedArgs); } catch (error) { return { error: error instanceof Error ? error.message : "Unknown error", success: false, }; }
• src/utils/ensembl-api.ts:198-232 (handler)

  Core implementation of the lookup logic in EnsemblApiClient.performLookup. Routes to specific Ensembl REST API endpoints based on lookup_type (id, symbol, xrefs, variant_recoder).
  async performLookup(args: any): Promise<any> { const { identifier, lookup_type = "id", species = "homo_sapiens", expand, external_db, } = args; const params: Record<string, string> = {}; if (expand && expand.length > 0) { params.expand = expand.join(","); } switch (lookup_type) { case "id": return this.makeRequest(`/lookup/id/${identifier}`, params); case "symbol": return this.makeRequest( `/lookup/symbol/${species}/${identifier}`, params ); case "xrefs": if (external_db) { return this.makeRequest(`/xrefs/name/${species}/${identifier}`, { external_db, }); } return this.makeRequest(`/xrefs/id/${identifier}`); case "variant_recoder": return this.makeRequest(`/variant_recoder/${species}/${identifier}`); default: throw new Error(`Unknown lookup_type: ${lookup_type}`); } }
• src/handlers/tools.ts:163-194 (schema)

  Input schema validation for the ensembl_lookup tool, defining parameters like identifier (required), lookup_type, species, expand, and external_db.
  inputSchema: { type: "object", properties: { identifier: { type: "string", description: "ID or symbol to look up (gene, transcript, variant, etc.) (e.g., 'ENSG00000141510', 'BRCA1', 'rs699', 'ENST00000288602')", }, lookup_type: { type: "string", enum: ["id", "symbol", "xrefs", "variant_recoder"], description: "Type of lookup to perform", default: "id", }, species: { type: "string", description: "Species name (e.g., 'homo_sapiens', 'mus_musculus')", default: "homo_sapiens", }, expand: { type: "array", items: { type: "string" }, description: "Additional data to include (e.g., ['Transcript', 'Exon'], ['Translation'], ['UTR'])", }, external_db: { type: "string", description: "External database name for xrefs lookup (e.g., 'HGNC', 'UniProtKB/Swiss-Prot', 'RefSeq_mRNA')", }, }, required: ["identifier"],
• src/handlers/tools.ts:159-196 (registration)

  Registration of the 'ensembl_lookup' tool in the ensemblTools array, which is used by the MCP server for tool listing and discovery.
  { name: "ensembl_lookup", description: "Look up genes, transcripts, variants by ID or symbol. Get cross-references and perform ID translation. Covers /lookup/* and /xrefs/* endpoints plus variant_recoder.", inputSchema: { type: "object", properties: { identifier: { type: "string", description: "ID or symbol to look up (gene, transcript, variant, etc.) (e.g., 'ENSG00000141510', 'BRCA1', 'rs699', 'ENST00000288602')", }, lookup_type: { type: "string", enum: ["id", "symbol", "xrefs", "variant_recoder"], description: "Type of lookup to perform", default: "id", }, species: { type: "string", description: "Species name (e.g., 'homo_sapiens', 'mus_musculus')", default: "homo_sapiens", }, expand: { type: "array", items: { type: "string" }, description: "Additional data to include (e.g., ['Transcript', 'Exon'], ['Translation'], ['UTR'])", }, external_db: { type: "string", description: "External database name for xrefs lookup (e.g., 'HGNC', 'UniProtKB/Swiss-Prot', 'RefSeq_mRNA')", }, }, required: ["identifier"], }, },
• src/utils/input-normalizer.ts:250-317 (helper)

  normalizeEnsemblInputs utility function used by the handler to standardize input parameters such as species names, genomic regions, and identifiers before API calls.
  export function normalizeEnsemblInputs(inputs: any): any { const normalized = { ...inputs }; // Normalize assembly first as it affects other normalizations if (normalized.assembly) { normalized.assembly = normalizeAssemblyName(normalized.assembly); } // Normalize species with assembly context if (normalized.species) { normalized.species = normalizeSpeciesName( normalized.species, normalized.assembly ); } // Normalize genomic regions with assembly context if (normalized.region) { normalized.region = normalizeGenomicRegion( normalized.region, normalized.assembly ); } // Normalize cDNA coordinates if (normalized.cdna_coords) { normalized.cdna_coords = normalizeCdnaCoordinates(normalized.cdna_coords); } // Normalize gene identifiers if (normalized.gene_id || normalized.feature_id) { const geneField = normalized.gene_id ? "gene_id" : "feature_id"; normalized[geneField] = normalizeGeneIdentifier( normalized[geneField], normalized.assembly ); } // Normalize HGVS notation if (normalized.hgvs) { normalized.hgvs = normalizeHgvsNotation( normalized.hgvs, normalized.assembly ); } // Normalize scaffold names if (normalized.scaffold) { normalized.scaffold = normalizeScaffoldName( normalized.scaffold, normalized.assembly ); } // Handle coordinate system normalization if specified if (normalized.start && normalized.end && normalized.coordinate_system) { const coords = normalizeCoordinateSystem( Number(normalized.start), Number(normalized.end), normalized.coordinate_system ); normalized.start = coords.start; normalized.end = coords.end; delete normalized.coordinate_system; // Remove the hint after using it } return normalized; }