Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:436-451 (handler)

  Primary handler function that normalizes input arguments and calls the Ensembl API client methods for feature overlap queries based on region or feature ID.

  export async function handleFeatureOverlap(args: any) {
    try {
      const normalizedArgs = normalizeEnsemblInputs(args);
      if (normalizedArgs.region) {
        return await ensemblClient.getOverlapByRegion(normalizedArgs);
      } else if (normalizedArgs.feature_id) {
        return await ensemblClient.getOverlapById(normalizedArgs);
      }
      throw new Error("Either region or feature_id must be provided");
    } catch (error) {
      return {
        error: error instanceof Error ? error.message : "Unknown error",
        success: false,
      };
    }
  }

• src/utils/ensembl-api.ts:75-98 (helper)

  EnsemblApiClient methods that perform the actual REST API requests to Ensembl's /overlap/region and /overlap/id endpoints.

  async getOverlapByRegion(args: any): Promise<any> {
    const { region, species = "homo_sapiens", feature_types, biotype } = args;
    const params: Record<string, string> = {};
  
    if (feature_types && feature_types.length > 0) {
      params.feature = feature_types.join(",");
    }
    if (biotype) {
      params.biotype = biotype;
    }
  
    return this.makeRequest(`/overlap/region/${species}/${region}`, params);
  }
  
  async getOverlapById(args: any): Promise<any> {
    const { feature_id, species = "homo_sapiens", feature_types } = args;
    const params: Record<string, string> = {};
  
    if (feature_types && feature_types.length > 0) {
      params.feature = feature_types.join(",");
    }
  
    return this.makeRequest(`/overlap/id/${feature_id}`, params);
  }

• src/handlers/tools.ts:12-43 (schema)

  JSON schema for tool inputs, including properties, descriptions, defaults, and validation requiring either 'region' or 'feature_id'.

  inputSchema: {
    type: "object",
    properties: {
      region: {
        type: "string",
        description:
          "Genomic region in format 'chromosome:start-end' (e.g., '17:7565096-7590856', 'X:1000000-2000000', '1:100000-200000'). Use this OR feature_id, not both.",
      },
      feature_id: {
        type: "string",
        description:
          "Feature ID (gene, transcript, etc.) to find overlapping features for (e.g., 'ENSG00000141510', 'ENST00000288602', 'BRCA1'). Use this OR region, not both.",
      },
      species: {
        type: "string",
        description:
          "Species name (e.g., 'homo_sapiens', 'mus_musculus', 'danio_rerio')",
        default: "homo_sapiens",
      },
      feature_types: {
        type: "array",
        items: { type: "string" },
        description:
          "Types of features to include (e.g., ['gene', 'transcript', 'exon'], ['regulatory', 'enhancer'])",
      },
      biotype: {
        type: "string",
        description:
          "Filter by biotype (e.g., 'protein_coding', 'lncRNA', 'miRNA', 'pseudogene')",
      },
    },
    oneOf: [{ required: ["region"] }, { required: ["feature_id"] }],

• index.ts:47-51 (registration)

  MCP server handler for listing tools, which returns the ensemblTools array containing the 'ensembl_feature_overlap' tool definition.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: ensemblTools,
    };
  });

• index.ts:61-73 (registration)

  Dispatch case in MCP CallToolRequest handler that invokes the tool's handler function when 'ensembl_feature_overlap' is called.

  case "ensembl_feature_overlap":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await handleFeatureOverlap(args),
            null,
            2
          ),
        },
      ],
    };