Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:923-958 (handler)

  The primary handler function for the 'lookup_gene' tool. Validates input using isValidGeneArgs, constructs the Ensembl REST API request to /lookup/id/{gene_id}, handles expand and format parameters, fetches data, and returns formatted JSON response or error.

  private async handleLookupGene(args: any) {
    if (!isValidGeneArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid gene lookup arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
      const format = args.format || 'json';
  
      let endpoint = `/lookup/id/${args.gene_id}`;
      const params: any = { species };
  
      if (args.expand) {
        params.expand = 1;
      }
  
      if (format !== 'json') {
        params.format = format;
      }
  
      const response = await this.apiClient.get(endpoint, { params });
  
      return {
        content: [
          {
            type: 'text',
            text: typeof response.data === 'object'
              ? JSON.stringify(response.data, null, 2)
              : String(response.data),
          },
        ],
      };
    } catch (error) {
      return this.handleError(error, 'looking up gene');
    }
  }

• src/index.ts:835-837 (registration)

  Registration of the 'lookup_gene' tool in the CallToolRequestSchema switch statement, dispatching to the handleLookupGene method.

  case 'lookup_gene':
    return this.handleLookupGene(args);
  case 'get_transcripts':

• src/index.ts:570-581 (schema)

  Tool schema definition including inputSchema for 'lookup_gene' provided in the ListToolsRequestSchema response.

  name: 'lookup_gene',
  description: 'Get detailed gene information by stable ID or symbol',
  inputSchema: {
    type: 'object',
    properties: {
      gene_id: { type: 'string', description: 'Ensembl gene ID or gene symbol (e.g., ENSG00000139618, BRCA2)' },
      species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
      expand: { type: 'boolean', description: 'Include transcript and exon details (default: false)' },
      format: { type: 'string', enum: ['json', 'fasta', 'gff'], description: 'Output format (default: json)' },
    },
    required: ['gene_id'],
  },

• src/index.ts:155-167 (helper)

  Type guard function for validating 'lookup_gene' tool arguments before execution.

  const isValidGeneArgs = (
    args: any
  ): args is { gene_id: string; species?: string; expand?: boolean; format?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.gene_id === 'string' &&
      args.gene_id.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.expand === undefined || typeof args.expand === 'boolean') &&
      (args.format === undefined || ['json', 'fasta', 'gff'].includes(args.format))
    );
  };

• src/index.ts:489-509 (registration)

  The handleLookupGene is also invoked in ReadResourceRequestSchema for URI ensembl://gene/{gene_id}, integrating gene lookup as a resource.

  const geneMatch = uri.match(/^ensembl:\/\/gene\/([^\/]+)$/);
  if (geneMatch) {
    const geneId = geneMatch[1];
    try {
      const result = await this.handleLookupGene({ gene_id: geneId });
      return {
        contents: [
          {
            uri: request.params.uri,
            mimeType: 'application/json',
            text: result.content[0].text,
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to fetch gene ${geneId}: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }