GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:664-746 (handler)

  Core handler function that validates geneIds input (max 20), fetches median gene expression data using GTExApiClient, groups expressions by gene, generates summary statistics and tissue ranges for each gene, and formats output as text suitable for clustering visualization and matrix analysis.
  async getClusteredExpression(args: any) { if (!args.geneIds || !Array.isArray(args.geneIds) || args.geneIds.length === 0) { throw new Error('geneIds parameter is required and must be a non-empty array of gene IDs'); } if (args.geneIds.length > 20) { return { content: [{ type: "text", text: "Maximum 20 genes can be processed for clustering analysis." }] }; } // Get median expression for all genes const result = await this.apiClient.getMedianGeneExpression( args.geneIds, args.datasetId || 'gtex_v8' ); if (result.error) { return { content: [{ type: "text", text: `Error retrieving clustered expression data: ${result.error}` }], isError: true }; } const expressions = result.data || []; if (expressions.length === 0) { return { content: [{ type: "text", text: "No expression data found for clustering analysis." }] }; } // Organize data for clustering visualization const geneGroups: { [key: string]: any[] } = {}; expressions.forEach(expr => { const key = `${expr.geneSymbol} (${expr.gencodeId})`; if (!geneGroups[key]) { geneGroups[key] = []; } geneGroups[key].push(expr); }); let output = `**Clustered Gene Expression Analysis**\n`; output += `Genes: ${Object.keys(geneGroups).length}\n`; output += `Dataset: ${expressions[0]?.datasetId}\n`; output += `Format: Median expression values for clustering\n\n`; // Create expression matrix summary output += `**Expression Matrix Summary:**\n`; Object.entries(geneGroups).forEach(([geneKey, geneExpressions]) => { const sortedExpr = geneExpressions.sort((a, b) => b.median - a.median); const stats = { max: Math.max(...sortedExpr.map(e => e.median)), min: Math.min(...sortedExpr.map(e => e.median)), tissues: sortedExpr.length }; output += `• **${geneKey}**:\n`; output += ` - Tissues: ${stats.tissues}\n`; output += ` - Range: ${stats.min.toFixed(3)} - ${stats.max.toFixed(3)} TPM\n`; output += ` - Top tissue: ${this.getTissueDisplayName(sortedExpr[0].tissueSiteDetailId)} (${sortedExpr[0].median.toFixed(3)})\n`; }); output += `\n**Clustering Notes:**\n`; output += `- Expression values are median TPM across samples\n`; output += `- Data suitable for hierarchical clustering or PCA analysis\n`; output += `- Consider log-transformation for clustering algorithms\n`; return { content: [{ type: "text", text: output }] }; }
• src/index.ts:153-170 (schema)

  Tool schema definition including name, description, and inputSchema specifying required gencodeIds array and optional datasetId.
  name: "get_clustered_expression", description: "Get clustered gene expression data for visualization", inputSchema: { type: "object", properties: { gencodeIds: { type: "array", items: { type: "string" }, description: "Array of GENCODE gene IDs" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeIds"] }
• src/index.ts:651-656 (registration)

  Tool registration in the main CallToolRequestHandler: routes 'get_clustered_expression' calls to expressionHandlers.getClusteredExpression, mapping input arguments appropriately.
  if (name === "get_clustered_expression") { return await expressionHandlers.getClusteredExpression({ gencodeIds: args?.gencodeIds || [], datasetId: args?.datasetId }); }
• src/index.ts:50-614 (registration)

  Includes the get_clustered_expression tool in the ListToolsRequestHandler response for tool discovery.
  return { tools: [ // Expression Analysis Tools (7 tools) { name: "get_gene_expression", description: "Get gene expression data across tissues for a specific gene", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId"] } }, { name: "get_median_gene_expression", description: "Get median gene expression levels across tissues", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId"] } }, { name: "get_top_expressed_genes", description: "Get top expressed genes in a specific tissue", inputSchema: { type: "object", properties: { tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (e.g., Muscle_Skeletal, Brain_Cortex)" }, filterMtGenes: { type: "boolean", description: "Filter out mitochondrial genes (default: true)", default: true }, sortBy: { type: "string", description: "Sort criteria (default: median)", enum: ["median", "mean"], default: "median" }, sortDirection: { type: "string", description: "Sort direction (default: desc)", enum: ["asc", "desc"], default: "desc" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["tissueSiteDetailId"] } }, { name: "get_tissue_specific_genes", description: "Get genes with tissue-specific expression patterns", inputSchema: { type: "object", properties: { tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (e.g., Muscle_Skeletal, Brain_Cortex)" }, selectionCriteria: { type: "string", description: "Selection criteria for tissue specificity (default: highestInGroup)", enum: ["highestInGroup", "aboveThreshold"], default: "highestInGroup" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["tissueSiteDetailId"] } }, { name: "get_clustered_expression", description: "Get clustered gene expression data for visualization", inputSchema: { type: "object", properties: { gencodeIds: { type: "array", items: { type: "string" }, description: "Array of GENCODE gene IDs" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeIds"] } }, { name: "calculate_expression_correlation", description: "Calculate expression correlation between genes across tissues", inputSchema: { type: "object", properties: { gencodeIds: { type: "array", items: { type: "string" }, description: "Array of GENCODE gene IDs to compare" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeIds"] } }, { name: "get_differential_expression", description: "Get differential gene expression between tissue groups", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, comparisonGroups: { type: "array", items: { type: "string" }, description: "Array of tissue groups to compare" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId", "comparisonGroups"] } }, // Association Analysis Tools (6 tools) { name: "get_eqtl_genes", description: "Get genes with eQTL associations for a genomic region", inputSchema: { type: "object", properties: { chr: { type: "string", description: "Chromosome (e.g., chr1, chr2, chrX)" }, start: { type: "integer", description: "Start position (1-based)" }, end: { type: "integer", description: "End position (1-based)" }, tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (optional, for tissue-specific results)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["chr", "start", "end"] } }, { name: "get_single_tissue_eqtls", description: "Get single-tissue eQTL results for a gene", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (e.g., Muscle_Skeletal, Brain_Cortex)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId", "tissueSiteDetailId"] } }, { name: "calculate_dynamic_eqtl", description: "Calculate dynamic eQTL effects across tissues", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, snpId: { type: "string", description: "SNP ID (rs number or variant ID)" }, tissueSiteDetailIds: { type: "array", items: { type: "string" }, description: "Array of tissue site detail IDs to compare" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId", "snpId", "tissueSiteDetailIds"] } }, { name: "get_multi_tissue_eqtls", description: "Get multi-tissue eQTL meta-analysis results", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId"] } }, { name: "get_sqtl_results", description: "Get splicing QTL (sQTL) results for a gene", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (optional, for tissue-specific results)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId"] } }, { name: "analyze_ld_structure", description: "Analyze linkage disequilibrium structure around eQTL variants", inputSchema: { type: "object", properties: { chr: { type: "string", description: "Chromosome (e.g., chr1, chr2, chrX)" }, position: { type: "integer", description: "Genomic position (1-based)" }, windowSize: { type: "integer", description: "Window size around position (default: 100000)", default: 100000 }, population: { type: "string", description: "Population for LD analysis (default: EUR)", enum: ["EUR", "AFR", "AMR", "EAS", "SAS"], default: "EUR" } }, required: ["chr", "position"] } }, // Reference/Dataset Tools (12 tools) { name: "search_genes", description: "Search for genes by symbol, name, or description", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query (gene symbol, name, or description)" }, species: { type: "string", description: "Species (default: human)", enum: ["human", "mouse"], default: "human" }, page: { type: "integer", description: "Page number for pagination (default: 0)", default: 0 }, pageSize: { type: "integer", description: "Number of results per page (default: 250)", default: 250 } }, required: ["query"] } }, { name: "get_gene_info", description: "Get detailed information about a specific gene", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, geneSymbol: { type: "string", description: "Gene symbol (alternative to gencodeId)" } } } }, { name: "get_variants", description: "Get genetic variants in a genomic region", inputSchema: { type: "object", properties: { chr: { type: "string", description: "Chromosome (e.g., chr1, chr2, chrX)" }, start: { type: "integer", description: "Start position (1-based)" }, end: { type: "integer", description: "End position (1-based)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["chr", "start", "end"] } }, { name: "get_tissue_info", description: "Get information about GTEx tissues and sample counts", inputSchema: { type: "object", properties: { datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } } } }, { name: "get_sample_info", description: "Get GTEx sample metadata and demographics", inputSchema: { type: "object", properties: { tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (optional, for tissue-specific samples)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } } } }, { name: "get_subject_phenotypes", description: "Get subject phenotype data and demographics", inputSchema: { type: "object", properties: { subjectId: { type: "string", description: "GTEx subject ID (optional, for specific subject)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } } } }, { name: "validate_gene_id", description: "Validate and normalize gene identifiers", inputSchema: { type: "object", properties: { geneId: { type: "string", description: "Gene ID to validate (GENCODE ID or gene symbol)" } }, required: ["geneId"] } }, { name: "validate_variant_id", description: "Validate variant identifiers and genomic coordinates", inputSchema: { type: "object", properties: { variantId: { type: "string", description: "Variant ID to validate (rs number or variant ID)" }, chr: { type: "string", description: "Chromosome (alternative validation method)" }, position: { type: "integer", description: "Genomic position (alternative validation method)" } } } }, { name: "get_dataset_info", description: "Get information about available GTEx datasets", inputSchema: { type: "object", properties: { datasetId: { type: "string", description: "Specific dataset ID (optional, returns all if not provided)" } } } }, { name: "search_transcripts", description: "Search for gene transcripts and isoforms", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, transcriptType: { type: "string", description: "Transcript type filter (optional)", enum: ["protein_coding", "lncRNA", "pseudogene", "miRNA"] } }, required: ["gencodeId"] } }, { name: "get_gene_ontology", description: "Get Gene Ontology annotations for a gene", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, ontologyType: { type: "string", description: "GO ontology type (optional)", enum: ["biological_process", "cellular_component", "molecular_function"] } }, required: ["gencodeId"] } }, { name: "convert_coordinates", description: "Convert between different genomic coordinate systems", inputSchema: { type: "object", properties: { chr: { type: "string", description: "Chromosome (e.g., chr1, chr2, chrX)" }, position: { type: "integer", description: "Genomic position to convert" }, fromBuild: { type: "string", description: "Source genome build (default: hg38)", enum: ["hg19", "hg38"], default: "hg38" }, toBuild: { type: "string", description: "Target genome build (default: hg19)", enum: ["hg19", "hg38"], default: "hg19" } }, required: ["chr", "position"] } } ] };