gnomad-genetics-mcp-server

---

概览

基于 gnomAD（Broad Institute）开展人群遗传学查询，并关联 NCBI 的 ClinVar 临床意义数据。查询各祖源的等位基因频率、基因功能缺失约束、基因变异目录和测序覆盖度，还可使用 SQL 查询大型结果集。

工具

工具	描述
gnomad_get_variant	一个或多个变异的完整人群记录——总体及各遗传祖源组的 AC/AN/AF、纯合子/半合子计数、质量标记、转录本后果、计算机预测因子，以及关联的 ClinVar 临床意义。
gnomad_get_gene_constraint	基因功能缺失约束——pLI、带置信区间的 LOEUF（oe_lof_upper）、观察值/预期值比率和 Z 分数。可按 HGNC 符号或 Ensembl 基因 ID 查询。
gnomad_list_gene_variants	列出基因、转录本或区域中的所有变异及其等位基因频率和预测后果，可按后果类别和最高等位基因频率筛选。
gnomad_get_coverage	基因、转录本或区域的测序覆盖度——按各调用集轨道提供平均/中位深度，以及超过深度阈值的样本比例。
gnomad_search_clinvar	通过 NCBI E-utilities 获取基因层级的 ClinVar 详情——已分类变异、审查状态、条件、提交次数，以及兼容 gnomAD 的变异 ID；支持按偏移量分页。
gnomad_dataframe_query	在列表工具暂存于画布表中的数据上运行只读 SQL SELECT 查询。
gnomad_dataframe_describe	在编写 SQL 前，列出画布上暂存的表及其列。
gnomad_dataframe_drop	从画布中删除指定表以释放内存。默认关闭；需通过 GNOMAD_DATAFRAME_DROP_ENABLED=true 启用。

资源

资源	描述
gnomad://variant/{dataset}/{variantId}	单个变异的人群记录——与 gnomad_get_variant 相同。
gnomad://gene/{dataset}/{gene}/constraint	基因功能缺失约束——与 gnomad_get_gene_constraint 相同。

所有资源数据也可通过工具访问。列表工具（gnomad_list_gene_variants、gnomad_get_coverage、gnomad_search_clinvar）返回分析用的行集，而非稳定的单 URI 文档，因此不会作为资源公开——请改用这些工具。

上游支持的工具和资源读取共享固定的 45 s 截止时间，涵盖队列等待、重试、响应正文和链式请求。变异批次中的所有项目共享此截止时间：已完成的结果仍可用，尚未完成的主项目会报告 upstream_timeout。调用方取消操作会导致调用被拒绝。

提示词

提示词	描述
gnomad_variant_triage	引导式罕见病变异分诊工作流：依次进行人群频率检查 → 基因约束检查 → 可调用性检查。

功能参考

gnomad_get_variant _工具

• 每次调用最多支持 25 个 ID（可通过 GNOMAD_MAX_VARIANT_BATCH 调高）；每个 ID 可以是染色体 1–22、X 或 Y 上的 chrom-pos-ref-alt 格式 variantId，可带可选的 chr 前缀（例如 1-55051215-G-GA），也可以是 rsID（例如 rs11591147）
• 错误或缺失的 ID 会被记录在 failed[] 中，格式为 { variant, error, reason, recovery }，且不会导致其余项目失败；线粒体 ID（M、MT、chrM）会以 mitochondrial_unsupported 失败；rsID 不明确时会附带 candidates
• 返回完整的各祖源频率向量、包含该变异的调用集、质量标记、后果、预测因子分数和 ClinVar 临床意义。即使仅 ClinVar 查询失败或过期，经过验证的人群记录仍会保留，并将 clinvar 设为 null、将 clinvar_unavailable 设为 true
• 检查每个 failed[].reason：只有 variant_not_found 表示该变异不在所选数据集中；超时和其他失败都无法确定该变异是否存在。解释变异缺失情况前，请先检查 gnomad_get_coverage

---

gnomad_get_gene_constraint _工具

• 接受 HGNC 符号（PCSK9）或 Ensembl 基因 ID（ENSG00000169174）

• 返回 pLI（>0.9 表示不耐受）、LOEUF / oe_lof_upper 及其下限、LoF / 错义 / 同义变异的观察值/预期值比率、三个 Z 分数，以及 constraint_flags（例如 no_exp_lof、syn_outlier）

• constraint_release 标明指标所属的版本。许多基因的 constraint 值为 null，将报告为 null：

  dataset	来源	constraint_release	LoF 不耐受性参考
  gnomad_r4	GRCh38 gnomAD constraint	gnomAD v4.1.2	LOEUF < 0.45
  gnomad_r3	GRCh38 gnomAD constraint（gnomAD 未发布 v3 constraint）	gnomAD v4.1.2	LOEUF < 0.45
  gnomad_r2_1	GRCh37 gnomAD constraint	gnomAD v2.1.1	LOEUF < 0.35
  exac	GRCh37 ExAC constraint	ExAC r0.3	仅 pLI

• 对于 exac，比率和 LOEUF 为 null，且 constraint_flags 为空

---

gnomad_list_gene_variants _工具

• 必须且只能提供 gene、transcript_id 或 region 其中之一（格式为 chrom-start-stop，坐标从 1 开始且包含端点；染色体为 1–22、X 或 Y，可选添加 chr 前缀）；空白的 gene 或 transcript_id 视为未提供
• 区域跨度必须小于 2,500,000 bp，且最多包含约 30,000 个变异，否则会因 invalid_region 或 region_too_large 而失败；线粒体目标会因 mitochondrial_unsupported 而失败
• 可选筛选条件：一个 consequence_class（lof / missense / synonymous / other）和/或最高等位基因频率
• 结果过大而无法内联时，会暂存到 gene_variants 画布表，并在预览旁返回 canvas_id 和 table_name；可使用 gnomad_dataframe_describe 检查，并使用 gnomad_dataframe_query 查询。传入 canvas_id 时，始终会将 gene_variants 写入该位置并替换之前的表。禁用画布（CANVAS_PROVIDER_TYPE=none）时，只返回数量受限的预览

---

gnomad_get_coverage _工具

• 必须且只能提供 gene、transcript_id 或 region 其中之一（格式与 gnomad_list_gene_variants 相同，且跨度上限为 2,500,000 bp）；空白的 gene 或 transcript_id 视为未提供。无效区域会因 invalid_region 或 region_too_large 而失败，线粒体目标则会因 mitochondrial_unsupported 而失败
• 按每个调用集轨道汇总返回平均和中位读取深度，以及在各阈值（1× 至 100×）下覆盖样本的平均比例；每个轨道还包含 bucket_size、bucket_count、已观察的 positions、目标位置总数 target_positions 和未观察的 missing_positions。缺失碱基会导致可调用性未知；统计数据仅描述返回的分桶，不会虚构零深度
• coverage_source 可限定为一个轨道（exome / genome）；省略则返回所有可用轨道
• 通知会说明目标区域不完整及缺失的受支持轨道。明确请求的不受支持轨道会单独标出（v3 仅支持 genome；ExAC 仅支持 exome）

---

gnomad_search_clinvar _工具

• 仅接受 HGNC 符号（传入 Ensembl 基因 ID 时会返回指引，不执行搜索）。可选筛选条件：clinical_significance（例如 pathogenic）和 min_review_stars（0–4）
• 返回临床意义、带 0–4 星评级的审核状态、相关病症、分子后果、提交数量，以及兼容 gnomAD 的标识符（canonical_spdi、rsids、grch38_variant_id）。ClinVar 没有摘要的 ID 会列在 unavailable_ids 中
• 每次调用最多分页获取 500 条记录，可使用 offset / limit（1–500）；total_found、truncated 和 next_offset 用于说明是否还有更多结果。limit 统计的是筛选前的记录数，因此一个分页窗口返回的行数可能更少
• 过大而无法内联的分页窗口会暂存到 clinvar_variants 画布表中（使用 gnomad_dataframe_describe 和 gnomad_dataframe_query 查询）；传入 canvas_id 时始终会将结果写入该表，并替换先前的表。设置 NCBI_API_KEY 可将速率限制从 3 req/s 提高到 10 req/s

---

gnomad_dataframe_query _工具

• 对由 gnomad_list_gene_variants 或 gnomad_search_clinvar 暂存的表（gene_variants 或 clinvar_variants）运行只读的单语句 SQL SELECT 查询；写入操作、DDL 以及文件/HTTP 表函数会被拒绝
• 使用 offset（默认值为 0）和 limit（默认值为 100，最大值为 500）分页；返回 rows、columns、total、truncated 和 next_offset（持续跟进，直到其值为 null）。使用唯一键执行 ORDER BY 可确保分页稳定；在 SQL 中筛选或聚合可突破 CANVAS_DEFAULT_ROW_LIMIT 上限（默认为 10,000）
• 若某行超过 10,000 个字符的分页预算，则会以 row_too_large 失败；设置 CANVAS_PROVIDER_TYPE=none 时，则会以 canvas_disabled 失败

---

gnomad_dataframe_describe _工具

• 列出画布上暂存的所有表及其行数和列架构（名称和 DuckDB 类型）
• 编写 gnomad_dataframe_query 的 SQL 前先调用此工具
• 画布关闭时（CANVAS_PROVIDER_TYPE=none），会以 canvas_disabled 错误失败

---

gnomad_dataframe_drop _工具

• 从画布中删除指定表以释放内存（destructiveHint: true）
• 通过 GNOMAD_DATAFRAME_DROP_ENABLED=true 启用；关闭时不会出现在 tools/list 中
• 未知或已过期的 canvas_id 会以 canvas_not_found 失败；设置 CANVAS_PROVIDER_TYPE=none 时，则会以 canvas_disabled 失败

---

gnomad://variant/{dataset}/{variantId} _资源

• 单个变异的群体记录，格式为 application/json，与 gnomad_get_variant 内容一致；variantId 接受 chrom-pos-ref-alt ID 或 rsID
• 类型化错误：invalid_variant_id、mitochondrial_unsupported、variant_not_found、ambiguous_rsid（包含 candidates）、graphql_error、upstream_build_mismatch、upstream_unavailable、upstream_timeout、upstream_access 和 invalid_upstream_response；每种错误都附带恢复提示

---

gnomad://gene/{dataset}/{gene}/constraint _资源

• 基因功能缺失约束数据，格式为 application/json，与 gnomad_get_gene_constraint 内容一致（每个 dataset 使用相同的 constraint_release）；gene 接受 HGNC 符号或 Ensembl 基因 ID
• 类型化错误：gene_not_found、invalid_constraint_data、graphql_error、upstream_unavailable、upstream_timeout、upstream_access 和 invalid_upstream_response；每种错误都附带恢复提示

---

gnomad_variant_triage _提示词

• 参数：必填的 variant（chrom-pos-ref-alt 或 rsID；格式错误时会被拒绝）；可选的 gene 和 dataset。dataset 可选 gnomad_r4、gnomad_r3、gnomad_r2_1、exac；未指定时使用服务默认值
• 将三个步骤串联为一条用户消息：群体频率（gnomad_get_variant）→ 基因约束（gnomad_get_gene_constraint）→ 可调用性检查（针对精确位置调用 gnomad_get_coverage）

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

gnomAD 专属功能：

• 整个核心功能仅使用一个无需密钥的 GraphQL 数据源 — ClinVar 临床意义会在 gnomAD 自身的响应中按变体关联
• dataset 和 reference_genome 是不同的参数，并经过一致性验证（v4/v3 ⇒ GRCh38，v2.1/ExAC ⇒ GRCh37）；每个工具的输出都会回显这两个参数，因此可以发现参考版本错误导致的坐标不匹配
• 遵循礼貌调用原则 — 针对由社区资助且设有速率限制的 API，采用保守的并发上限（GNOMAD_MAX_CONCURRENCY，默认值为 2）和指数退避
• 对话内 SQL 分析：gnomad_list_gene_variants 和 gnomad_search_clinvar 会将过大而无法直接内联的结果暂存到由 DuckDB 支持的画布表中 — gnomad_dataframe_describe 会列出其列，gnomad_dataframe_query 会对所有行执行 SQL

便于 Agent 使用的输出：

• 完整返回各祖源的等位基因频率向量，不会合并为单个全局 AF
• gnomad_get_variant 会返回逐项的 failed[] 行，而不是让整个批次失败
• 每个响应都会回显生效的 dataset 和 reference_genome；上游字段为 null 时仍保持 null
• 每个错误都包含类型化的 reason（例如 incoherent_build、invalid_target、variant_not_found、upstream_timeout、canvas_disabled）和恢复提示

开始使用

公共托管实例

公共实例位于 https://gnomad-genetics.caseyjhand.com/mcp — 无需安装。该实例使用 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http gnomad-genetics-mcp-server https://gnomad-genetics.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "gnomad-genetics-mcp-server": {
      "type": "streamableHttp",
      "url": "https://gnomad-genetics.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "gnomad-genetics-mcp-server": {
      "url": "https://gnomad-genetics.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置” →“连接器”中添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。gnomAD 是免费的、无需密钥的 API — 无需凭据。

{
  "mcpServers": {
    "gnomad-genetics-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gnomad-genetics-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "gnomad-genetics-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gnomad-genetics-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "gnomad-genetics-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/gnomad-genetics-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

SQL 分析路径默认使用 DuckDB — @duckdb/node-api 已作为依赖项提供，因此无需额外安装。设置 CANVAS_PROVIDER_TYPE=none 可将其关闭。Claude Desktop 软件包（.mcpb）不包含 DuckDB 的原生绑定，运行时会关闭画布。

前置要求

• Bun v1.4.0](https://bun.sh/) 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — gnomAD 的 GraphQL 端点无需密钥。可选的 NCBI_API_KEY 可提高 gnomad_search_clinvar 的速率限制。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/gnomad-genetics-mcp-server.git

2. 进入目录：

cd gnomad-genetics-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# all vars are optional — the server runs keyless out of the box

配置

所有变量均为可选；服务在不提供密钥时会使用以下默认值运行。

Node 和 Bun 会在构建工具定义前加载工作目录中的 .env。已导出的值优先；空值使用架构默认值。公布的变体数量上限、对应的输入验证以及丢弃工具的注册开关也使用相同的设置。服务器配置无效时会在启动失败提示中指出变量名称；DEBUG=true 时会包含堆栈信息。

变量	说明	默认值
GNOMAD_API_BASE_URL	gnomAD GraphQL 端点。可覆盖为私有镜像或用于测试。	https://gnomad.broadinstitute.org/api
GNOMAD_DEFAULT_DATASET	工具调用未提供 dataset 时使用的数据集（gnomad_r4 / gnomad_r3 / gnomad_r2_1 / exac）。	gnomad_r4
GNOMAD_REQUEST_TIMEOUT_MS	每次尝试的 gnomAD/NCBI 超时时间（毫秒），受共享的 45 秒调用时限约束。	30000
GNOMAD_MAX_CONCURRENCY	并发上游请求数上限——以示对社区资助 API 的尊重。	2
GNOMAD_MAX_VARIANT_BATCH	每次 gnomad_get_variant 调用接受的变体 ID 数量上限。	25
CLINVAR_BASE_URL	gnomad_search_clinvar 使用的 NCBI E-utilities 基础 URL。	https://eutils.ncbi.nlm.nih.gov/entrez/eutils
NCBI_API_KEY	可选的 NCBI 密钥。将 E-utilities 速率限制从 3 提高到 10 req/s。	—
CANVAS_PROVIDER_TYPE	列表工具底层的 DataCanvas 后端，用于溢出/SQL 路径。none 会禁用该后端，此时列表工具会返回有上限的内联预览。	duckdb
GNOMAD_DATAFRAME_DROP_ENABLED	可选启用的 gnomad_dataframe_drop 工具开关。默认关闭。	false
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t gnomad-genetics-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 gnomad-genetics-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/gnomad-genetics-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具/资源/提示词并初始化服务。
src/config	使用 Zod 解析和验证服务器专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）和共享输入架构。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。
src/services/gnomad	gnomAD GraphQL 客户端、查询文档和领域类型。
src/services/clinvar	用于可选 ClinVar 工具的 NCBI E-utilities 客户端。
src/services/canvas-accessor.ts	框架可选 DataCanvas 的模块级访问器。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明如下：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

数据来源

gnomAD 数据由 Genome Aggregation Database（Broad Institute）提供。ClinVar 数据由 NCBI 提供。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。