gnomAD MCP Server

gnomAD MCP 服务

概述

此 MCP 服务提供了 Genome Aggregation Database（gnomAD）API 的编程接口，支持多个 API 版本（v2.1.1、v3.1.2、v4.1.0）。
它抽象了各版本间的字段和架构差异，为下游工具和用户提供统一的 API。

状态

🚧 正在积极开发中 🚧

此项目正在积极开发中。API 和功能可能会随时更改，恕不另行通知。

支持的 gnomAD API 版本

• v4.1.0（gnomad_r4）
• v3.1.2（gnomad_r3）
• v2.1.1（gnomad_r2_1）

各版本支持的查询

下表总结了各 gnomAD API 版本支持的查询：

查询类型	描述	v2	v3	v4
get_gene_info	获取基因元数据和约束指标（通过 gene_id/gene_symbol 直接查询）	❌	❌	✅
get_region_info	获取基因组区域的变异和汇总信息	❌	❌	✅
get_variant_info	获取变异元数据和人群频率数据（通过 variantId 查询）	✅	✅	✅
get_clinvar_variant_info	获取 ClinVar 变异数据和临床意义	✅	✅	✅
get_mitochondrial_variant_info	获取线粒体变异数据和人群频率	❌	❌	✅
get_structural_variant_info	获取结构变异（SV）数据和人群频率	✅	❌	✅
get_copy_number_variant_info	获取拷贝数变异（CNV）数据和人群频率	❌	❌	✅
search_for_genes	按符号或名称搜索基因（v2/v3 不支持直接通过 gene_id 查询）	✅	✅	✅
search_for_variants	按 ID、基因或区域搜索变异	✅	✅	✅
get_str_info	获取短串联重复序列（STR）数据和人群频率	❌	❌	✅
get_all_strs	获取数据集中的所有 STR	❌	❌	✅
get_variant_liftover	获取变异在不同基因组间的 liftover 映射	✅	❌	❌
get_metadata	获取 gnomAD 浏览器元数据和 API 版本信息	✅	✅	✅

• ✅ = 此版本支持
• ❌ = 此版本不支持

依赖项

• Python >= 3.13
• aiohttp >= 3.11.18
• fastmcp >= 2.2.1
• gql >= 3.5.2
• httpx >= 0.28.1
• mcp[cli] >= 1.6.0
• nest-asyncio >= 1.6.0
• pytest >= 8.3.5
• pytest-asyncio >= 0.26.0

目录结构

.
├── gnomad/              # Main package
│   ├── __init__.py
│   ├── types.py         # Type definitions
│   ├── queries/         # GraphQL query templates
│   │   ├── v2/         # v2.1 specific queries
│   │   ├── v3/         # v3 specific queries
│   │   └── v4/         # v4 specific queries
│   └── schemas/         # Versioned schema files
├── tests/               # Test code and data
│   ├── input/          # Test input data
│   │   ├── analyzed_schemas/  # Analyzed schema data
│   │   ├── schema2query/     # Schema to query conversion
│   │   └── schemas/          # Raw schema files
│   ├── output/         # Test output data
│   │   ├── server/     # Server test outputs
│   │   ├── v2/         # v2.1 test outputs
│   │   ├── v3/         # v3 test outputs
│   │   └── v4/         # v4 test outputs
│   ├── scripts/        # Test utility scripts
│   └── tests/          # Additional test modules
├── server.py           # FastMCP server entrypoint
├── pyproject.toml      # Project metadata
├── README.md           # This file
└── README_tests.md     # Testing documentation

安装

安装依赖项

uv sync

激活虚拟环境

. .venv/bin/activate

测试服务

uv --directory ./ run mcp dev server.py

将 MCP 服务添加到 MCP 服务列表（Claude、Cursor 等）

{
    "mcpServers": {
      "gnomad": {
        "command": "uv",
        "args": ["--directory", "where you cloned the repo", "run", "server.py"],
        "env": {}
      }
    }
}

运行测试

请参阅 README_tests.md

查询与 API 设计

• 使用 QueryTemplateEngine 模式管理特定版本的 GraphQL 查询模板。
• 目前，查询是固定的；请参阅（./gnomad/queries）
  • 查询通过 schema_fetcher.py 和 schema_analyzer.py 获取
  • TODO：动态查询
• MCP 工具端点均附有详细的参数和输出说明。

许可证

此 MCP 服务本身采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

此项目使用 gnomAD API。使用此工具或其输出时，请确保引用 gnomAD。

致谢

• gnomAD
• FastMCP