Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:1290-1336 (handler)

  The handler function that implements the get_variants tool. It validates input, queries the Ensembl API using /overlap/region (feature=variation) or falls back to /variation/region, and returns the variants data as JSON.

  private async handleGetVariants(args: any) {
    if (!isValidVariantArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid variant arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
      const format = args.format || 'json';
      const region = this.formatGenomicRegion(args.region);
  
      // Try overlap endpoint first as variation/region may not have data for all regions
      try {
        const response = await this.apiClient.get(`/overlap/region/${species}/${region}`, {
          params: { feature: 'variation' }
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      } catch (overlapError) {
        // Fallback to variation endpoint
        const params: any = { format };
  
        if (args.consequence_type) {
          params.consequence_type = args.consequence_type.join(',');
        }
  
        const response = await this.apiClient.get(`/variation/region/${species}/${region}`, { params });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      }
    } catch (error) {
      return this.handleError(error, 'fetching variants');
    }
  }

• src/index.ts:684-695 (registration)

  Tool registration in the ListToolsRequestSchema response, defining the name, description, and input schema for get_variants.

  name: 'get_variants',
  description: 'Get genetic variants in a genomic region',
  inputSchema: {
    type: 'object',
    properties: {
      region: { type: 'string', description: 'Genomic region (chr:start-end)' },
      species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
      format: { type: 'string', enum: ['json', 'vcf'], description: 'Output format (default: json)' },
      consequence_type: { type: 'array', items: { type: 'string' }, description: 'Filter by consequence types' },
    },
    required: ['region'],
  },

• src/index.ts:199-212 (schema)

  Type guard function that validates the input parameters for the get_variants tool.

  const isValidVariantArgs = (
    args: any
  ): args is { region: string; species?: string; format?: string; consequence_type?: string[] } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.region === 'string' &&
      args.region.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.format === undefined || ['json', 'vcf'].includes(args.format)) &&
      (args.consequence_type === undefined ||
       (Array.isArray(args.consequence_type) && args.consequence_type.every((c: any) => typeof c === 'string')))
    );
  };

• src/index.ts:854-855 (registration)

  Registration/dispatch in the CallToolRequestSchema switch statement that routes calls to get_variants to its handler.

  case 'get_variants':
    return this.handleGetVariants(args);

• src/index.ts:64-77 (schema)

  TypeScript interface defining the structure of Ensembl variant data objects returned by the API.

  interface EnsemblVariant {
    id: string;
    seq_region_name: string;
    start: number;
    end: number;
    strand: number;
    allele_string: string;
    variant_class: string;
    source: string;
    most_severe_consequence: string;
    MAF?: number;
    minor_allele?: string;
    clinical_significance?: string[];
  }