Ensembl MCP Server

Instructions

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,
    };