ensembl_lookup
Look up genes, transcripts, and variants by ID or symbol in the Ensembl database. Retrieve cross-references and translate identifiers across genomic databases.
Instructions
Look up genes, transcripts, variants by ID or symbol. Get cross-references and perform ID translation. Covers /lookup/* and /xrefs/* endpoints plus variant_recoder.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ID or symbol to look up (gene, transcript, variant, etc.) (e.g., 'ENSG00000141510', 'BRCA1', 'rs699', 'ENST00000288602') | |
| lookup_type | No | Type of lookup to perform | id |
| species | No | Species name (e.g., 'homo_sapiens', 'mus_musculus') | homo_sapiens |
| expand | No | Additional data to include (e.g., ['Transcript', 'Exon'], ['Translation'], ['UTR']) | |
| external_db | No | External database name for xrefs lookup (e.g., 'HGNC', 'UniProtKB/Swiss-Prot', 'RefSeq_mRNA') |
Implementation Reference
- src/handlers/tools.ts:159-196 (schema)Input schema and tool definition for the 'ensembl_lookup' tool within the ensemblTools array.{ 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/handlers/tools.ts:489-498 (handler)Tool handler function that normalizes inputs and delegates to EnsemblApiClient.performLookup.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 executing the lookup logic by routing to specific Ensembl REST API endpoints based on lookup_type.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}`); } }
- index.ts:109-117 (registration)Dispatcher switch case registering the 'ensembl_lookup' tool handler in the MCP server request handler.case "ensembl_lookup": return { content: [ { type: "text", text: JSON.stringify(await handleLookup(args), null, 2), }, ], };
- index.ts:47-50 (registration)Registration of tool list handler that returns ensemblTools array including 'ensembl_lookup'.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: ensemblTools, };