Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:960-994 (handler)

  The handler function for the 'get_transcripts' tool. Validates input, queries Ensembl REST API for gene with expanded transcripts, filters optionally for canonical transcripts, and returns formatted JSON with gene info and transcripts.

  private async handleGetTranscripts(args: any) {
    if (!isValidTranscriptArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid transcript arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
      const response = await this.apiClient.get(`/lookup/id/${args.gene_id}`, {
        params: { species, expand: 1 },
      });
  
      const gene = response.data;
      let transcripts = gene.Transcript || [];
  
      if (args.canonical_only) {
        transcripts = transcripts.filter((t: any) => t.is_canonical === 1);
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              gene_id: gene.id,
              gene_name: gene.display_name,
              transcript_count: transcripts.length,
              transcripts: transcripts,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.handleError(error, 'fetching transcripts');
    }
  }

• src/index.ts:584-595 (registration)

  Registration of the 'get_transcripts' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

    name: 'get_transcripts',
    description: 'Get all transcripts for a gene with detailed structure',
    inputSchema: {
      type: 'object',
      properties: {
        gene_id: { type: 'string', description: 'Ensembl gene ID' },
        species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
        canonical_only: { type: 'boolean', description: 'Return only canonical transcript (default: false)' },
      },
      required: ['gene_id'],
    },
  },

• src/index.ts:838-839 (registration)

  Routes calls to the 'get_transcripts' tool to its handler function in the CallToolRequestSchema switch statement.

    return this.handleGetTranscripts(args);
  case 'search_genes':

• src/index.ts:283-294 (schema)

  Type guard function for validating input arguments to the 'get_transcripts' tool.

  const isValidTranscriptArgs = (
    args: any
  ): args is { gene_id: string; species?: string; canonical_only?: boolean } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.gene_id === 'string' &&
      args.gene_id.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.canonical_only === undefined || typeof args.canonical_only === 'boolean')
    );
  };