gtex MCP

GTEx MCP服务器

模型上下文协议（MCP）服务器提供对GTEx门户数据库的访问，用于基因表达分析、组织特异性基因发现和eQTL分析。

目录

• 概述
• 安装
• 本地使用（脚本）
• MCP服务器安装
• 使用Claude代码
• 与Gemini CLI一起使用
• 可用工具
• 例子
• 故障排除

概述

GTEx MCP Server是一个模型上下文协议（MCP）服务器，通过独立的Python脚本和集成的MCP服务器提供对GTEx门户数据库的编程访问。它使研究人员能够查询基因表达数据，发现组织特异性基因，并从全面的GTEx Portal数据集中分析表达数量性状位点（eQTL）。

特性

• 基因表达分析：查询特定基因在组织中的表达水平
• 组织特异性基因发现：识别具有高组织特异性的基因
• eQTL分析：分析表达数量性状位点关联
• 双接口：在Claude Code/GGemini CLI中用作独立脚本或MCP工具
• 综合API：同步（快速）和异步（批处理）操作
• 生产就绪：强大的错误处理、验证和日志记录

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   ├── server.py           # MCP server
│   ├── jobs/               # Background job management
│   └── tools/              # Tool implementations
├── scripts/
│   ├── gene_expression_analysis.py  # Gene expression queries
│   ├── tissue_specific_genes.py     # Tissue-specific gene discovery
│   ├── eqtl_analysis.py             # eQTL association analysis
│   └── lib/                         # Shared utilities
├── examples/
│   └── data/               # Demo data files
├── configs/                # Configuration files
├── tests/                  # Integration tests
└── reports/                # Documentation from development

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• GTEx门户API调用的互联网访问

创建环境

请严格遵守中的信息 reports/step3_environment.md 详细的环境设置。建议的工作流程是：

# Navigate to the MCP directory
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/gtex_mcp

# Check package manager (prefer mamba over conda)
if command -v mamba &> /dev/null; then
    PKG_MGR="mamba"
else
    PKG_MGR="conda"
fi
echo "Using package manager: $PKG_MGR"

# Create conda environment (use mamba if available)
mamba create -p ./env python=3.11 -y
# or: conda create -p ./env python=3.11 -y

# Activate environment
mamba activate ./env
# or: conda activate ./env

安装依赖项

# Install core dependencies
mamba run -p ./env pip install loguru click pandas numpy requests tqdm fastapi uvicorn aiohttp

# Install MCP framework
mamba run -p ./env pip install mcp

# Install additional MCP tools
pip install fastmcp loguru --ignore-installed

______________________________________________________________________

本地使用（脚本）

您可以在没有MCP的情况下直接使用脚本进行本地处理。

可用脚本

脚本示例

基因表达分析

# Activate environment
mamba activate ./env

# Run gene expression analysis
python scripts/gene_expression_analysis.py \
  --genes BRCA1,TP53 \
  --tissues Brain_Cortex,Heart_Left_Ventricle \
  --output results/expression.json

参数：

• --genes, -g：逗号分隔的基因ID或符号（必填）
• --tissues, -t：逗号分隔的组织ID（可选）
• --dataset, -d：GTEx数据集ID（默认值：GTEx_v8）
• --output, -o：输出JSON文件路径（可选）
• --input, -i：带有基因列表的输入文件（替代--genes）
• --config, -c：配置文件路径（可选）

组织特异性基因发现

python scripts/tissue_specific_genes.py \
  --tissue Brain_Cortex \
  --limit 20 \
  --output brain_markers.json

参数：

• --tissue, -t：目标组织ID（必填）
• --limit, -l：要返回的最大基因数（默认值：50）
• --dataset, -d：GTEx数据集ID（默认值：GTEx_v8）
• --no-filter-mt：不要过滤线粒体基因
• --no-specificity：跳过组织特异性计算
• --output, -o：输出JSON文件路径（可选）

eQTL分析

# Gene-based eQTL analysis
python scripts/eqtl_analysis.py \
  --gene ENSG00000012048.20 \
  --tissues Liver,Brain_Cortex \
  --output eqtl_results.json

# Region-based eQTL analysis
python scripts/eqtl_analysis.py \
  --region chr17:43000000-43200000 \
  --tissues Liver \
  --output region_eqtls.json

参数：

• --gene, -g：用于基因分析的基因ID（可选）
• --region, -r：用于区域分析的基因组区域（chr：开始-结束）（可选）
• --tissues, -t：逗号分隔的组织ID（可选）
• --dataset, -d：GTEx数据集ID（默认值：GTEx_v8）
• --output, -o：输出JSON文件路径（可选）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
fastmcp install src/server.py --name GTEx-MCP-Server

选项2:Claude代码的手动安装

# Add MCP server to Claude Code
claude mcp add GTEx-MCP-Server -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "GTEx-MCP-Server": {
      "command": "/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/gtex_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/gtex_mcp/src/server.py"]
    }
  }
}

______________________________________________________________________

使用Claude代码

安装MCP服务器后，您可以直接在Claude Code中使用它。

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from GTEx-MCP-Server?

基本用法

Use analyze_gene_expression with genes BRCA1,TP53 and tissues Brain_Cortex,Heart_Left_Ventricle

带有文件引用

Analyze genes from @examples/data/sample_genes.txt across @examples/data/sample_tissues.txt

配置使用

Run tissue-specific analysis for Brain_Cortex using config @configs/tissue_specific_config.json

长期运行任务（提交API）

Submit gene expression analysis for genes from @examples/data/sample_genes.txt for batch processing
Then check the job status

批处理

Process these files in batch:
- @examples/data/sample_genes.txt for gene expression
- @examples/data/sample_regions.txt for eQTL analysis

使用@引用

在克劳德代码中，使用 @ 引用文件和目录：

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "GTEx-MCP-Server": {
      "command": "/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/gtex_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/gtex_mcp/src/server.py"]
    }
  }
}

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use analyze_gene_expression with genes BRCA1,TP53

______________________________________________________________________

可用工具

快速操作（同步API）

这些工具会立即返回结果（\10分钟）：

作业管理工具

______________________________________________________________________

例子

实例1：基因表达谱分析

目标： 分析癌症基因在脑和心脏组织中的表达

使用脚本：

python scripts/gene_expression_analysis.py \
  --genes BRCA1,BRCA2,TP53 \
  --tissues Brain_Cortex,Heart_Left_Ventricle \
  --output results/cancer_genes.json

使用MCP（克劳德代码）：

Use analyze_gene_expression with gene_ids "BRCA1,BRCA2,TP53" and tissue_ids "Brain_Cortex,Heart_Left_Ventricle" and save to results/cancer_genes.json

预期产量：

• 每个组织TPM中值的基因表达数据
• 包括基因/组织计数在内的汇总统计数据
• 关于API查询和数据集版本的元数据

示例2：组织特异性生物标志物发现

目标： 为神经学研究寻找大脑特异性基因

使用脚本：

python scripts/tissue_specific_genes.py \
  --tissue Brain_Cortex \
  --limit 20 \
  --output brain_markers.json

使用MCP（克劳德代码）：

Run find_tissue_specific_genes for tissue_id "Brain_Cortex" with limit 20 and save to brain_markers.json

预期产量：

• 大脑皮层中表达最高的前20个基因
• 所有组织的组织特异性评分比较
• 基因排名和表达统计

示例3:eQTL关联分析

目标： 寻找影响BRCA1表达的遗传变异

使用脚本：

python scripts/eqtl_analysis.py \
  --gene ENSG00000012048.20 \
  --tissues Breast_Mammary_Tissue,Ovary \
  --output brca1_eqtls.json

使用MCP（克劳德代码）：

Use analyze_eqtls with gene_id "ENSG00000012048.20" and tissue_ids "Breast_Mammary_Tissue,Ovary"

预期产量：

• eQTL与效应大小和p值的关联
• 变异位置和等位基因信息
• 组织特异性和多组织荟萃分析结果

示例4：批处理

目标： 一次处理多个文件

使用脚本：

for f in examples/data/sample_*.txt; do
  python scripts/gene_expression_analysis.py --input "$f" --output results/batch/
done

使用MCP（克劳德代码）：

Submit batch processing:
1. Submit gene expression analysis for genes from @examples/data/sample_genes.txt
2. Submit tissue analysis for tissues from @examples/data/sample_tissues.txt
3. Submit eQTL analysis for regions from @examples/data/sample_regions.txt

______________________________________________________________________

演示数据

这 examples/data/ 目录包含用于测试的示例数据：

______________________________________________________________________

配置文件

这 configs/ 目录包含配置模板：

配置示例

{
  "api": {
    "base_url": "https://gtexportal.org/api/v2",
    "timeout": 30,
    "max_retries": 3
  },
  "gtex": {
    "default_dataset": "gtex_v8",
    "max_genes": 60,
    "items_per_page": 250
  },
  "output": {
    "format": "json",
    "include_metadata": true
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.11 -y
mamba activate ./env
pip install loguru click pandas numpy requests tqdm fastapi uvicorn aiohttp mcp

问题： 导入错误

# Verify installation
python -c "from src.server import mcp; print('MCP server loaded successfully')"

MCP问题

问题： 在Claude代码中找不到服务器

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove GTEx-MCP-Server
claude mcp add GTEx-MCP-Server -- $(pwd)/env/bin/python $(pwd)/src/server.py

问题： 工具不工作

# Test server directly
python -c "
from src.server import mcp
print(list(mcp.list_tools().keys()))
"

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job log
cat jobs//job.log

问题： 作业失败

Use get_job_log with job_id "" and tail 100 to see error details

API问题

问题： GTEx门户连接错误

# Test API connectivity
curl -s https://gtexportal.org/api/v2/dataset | head -5

问题： 基因/组织验证错误

# Use validation tools
python -c "
from scripts.gene_expression_analysis import GTExAPIClient
client = GTExAPIClient()
print(client.get_expression_data(['BRCA1']))"

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Run integration tests
python tests/run_integration_tests.py

正在启动开发服务器

# Run MCP server in dev mode
fastmcp dev src/server.py

性能优化

该服务器包括几个性能特征：

• 重复查询的响应缓存
• API调用的速率限制
• 大型数据集的后台作业处理
• HTTP请求的连接池

______________________________________________________________________

API 参考

GTEx门户API集成

此MCP服务器与GTEx门户API v2接口：

• 基础URL: https://gtexportal.org/api/v2/
• 认证：不需要（公共API）
• 速率限制：在客户端自动处理
• 支持的端点：表达、eQTL、组织数据

错误处理

所有工具都提供一致的错误响应：

{
  "status": "error",
  "error": "Description of the error",
  "details": "Additional context if available"
}

成功响应

成功操作返回：

{
  "status": "success",
  "data": "Tool-specific results",
  "metadata": {
    "query_time": "ISO timestamp",
    "api_version": "gtex_v8",
    "total_results": 42
  }
}

______________________________________________________________________

许可证

该项目基于原始的GTEx MCP Server TypeScript实现，并已针对Python MCP的使用进行了调整。有关许可条款，请参阅原始存储库。

学分

基于 GTEx MCP服务器 -TypeScript实现适应Python MCP框架。

______________________________________________________________________

科学应用

基因表达分析

• 疾病基因特征
• 组织特异性生物标志物的发现
• 比较表达分析
• RNA-seq实验的质量控制

eQTL发现

• 遗传关联研究
• 监管变体识别
• 个性化医学研究
• 群体遗传学分析

组织生物学

• 发展研究
• 疾病机制研究
• 治疗靶点识别
• 跨物种比较分析