gnomad-genetics-mcp-server

---

概要

gnomAD（Broad Institute）の集団遺伝学データに、NCBI の ClinVar 臨床的意義を結合します。祖先集団別のアレル頻度、遺伝子の機能喪失制約、遺伝子バリアントカタログ、シーケンスカバレッジを検索し、大規模な結果セットを SQL でクエリできます。

ツール

ツール	説明
gnomad_get_variant	1 つ以上のバリアントの完全な集団レコード — 全体および遺伝的祖先グループごとの 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	list ツールによってキャンバスにステージングされたテーブルに対して、読み取り専用 SQL SELECT を実行します。
gnomad_dataframe_describe	SQL を記述する前に、キャンバスにステージングされたテーブルとその列を一覧表示します。
gnomad_dataframe_drop	メモリを解放するため、キャンバスから名前を指定したテーブルを削除します。GNOMAD_DATAFRAME_DROP_ENABLED=true によるオプトインが必要です — デフォルトでは無効です。

リソース

リソース	説明
gnomad://variant/{dataset}/{variantId}	1 つのバリアントの集団レコード — gnomad_get_variant と同等です。
gnomad://gene/{dataset}/{gene}/constraint	遺伝子の機能喪失制約 — gnomad_get_gene_constraint と同等です。

すべてのリソースデータにはツールからもアクセスできます。list ツール（gnomad_list_gene_variants、gnomad_get_coverage、gnomad_search_clinvar）は安定した単一 URI のドキュメントではなく、分析用の行セットを返すため、リソースとしては公開されていません — 代わりにツールを呼び出してください。

上流に接続するツールとリソースの読み取りでは、キュー待ち、再試行、レスポンスボディ、連鎖リクエストを通じて、固定の 45 s の期限を共有します。バリアントの一括処理では、すべての項目でこの期限を共有します。完了した結果は引き続き利用でき、未完了の主項目は upstream_timeout を報告します。呼び出し元がキャンセルすると、呼び出しは拒否されます。

プロンプト

プロンプト	説明
gnomad_variant_triage	希少疾患のバリアントトリアージをガイドするワークフロー：集団頻度 → 遺伝子制約 → コール可能性の確認の順に実行します。

機能リファレンス

gnomad_get_variant _tool

• 1 回の呼び出しで最大 25 個の ID を指定できます（GNOMAD_MAX_VARIANT_BATCH で上限を引き上げ可能）。各 ID は、染色体 1–22、X、または Y 上の chrom-pos-ref-alt 形式の variantId（オプションで chr プレフィックスを付加。例：1-55051215-G-GA）または rsID（例：rs11591147）です。
• 無効または指定されていない ID は、残りの処理を失敗させることなく { variant, error, reason, recovery } として failed[] に格納されます。ミトコンドリア 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 _tool

• HGNC シンボル（PCSK9）または Ensembl 遺伝子 ID（ENSG00000169174）を指定します

• pLI（>0.9 は不耐性）、LOEUF／下限値付きの oe_lof_upper、LoF／ミスセンス／同義置換の観測値と期待値の比率、3 つの Z スコア、および constraint_flags（例：no_exp_lof、syn_outlier）を返します

• constraint_release はメトリクスの取得元リリースを示します。多くの遺伝子では constraint が null であり、null として報告されます：

  dataset	Source	constraint_release	LoF-intolerance guidance
  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 _tool

• gene、transcript_id、region（chrom-start-stop 形式、1-based の両端を含む。染色体は 1～22、X、Y。chr プレフィックスは任意）のいずれか 1 つだけを指定します。空の gene または transcript_id は未指定として扱われます
• region の長さは 2,500,000 bp 未満、含まれる変異は約 30,000 件以下である必要があります。条件を満たさない場合は invalid_region または region_too_large で失敗します。ミトコンドリアを対象とする場合は mitochondrial_unsupported で失敗します
• 任意のフィルター：consequence_class（lof／missense／synonymous／other）を 1 つ、および／または最大アレル頻度を指定できます
• インラインで返すには大きすぎる結果は gene_variants キャンバステーブルに保存され、プレビューとともに canvas_id および table_name として返されます。gnomad_dataframe_describe で内容を確認し、gnomad_dataframe_query でクエリを実行できます。canvas_id を渡すと、常にそこへ gene_variants が書き込まれ、以前のテーブルは置き換えられます。キャンバスが無効（CANVAS_PROVIDER_TYPE=none）の場合は、上限付きのプレビューのみが返されます

---

gnomad_get_coverage _tool

• gene、transcript_id、region（gnomad_list_gene_variants と同じ chrom-start-stop 形式および 2,500,000 bp の上限）のいずれか 1 つだけを指定します。空の gene または transcript_id は未指定として扱われます。不正な region は invalid_region または region_too_large で失敗し、ミトコンドリアを対象とする場合は mitochondrial_unsupported で失敗します
• 平均および中央値のリード深度に加え、各しきい値（1×～100×）でカバーされるサンプルの平均割合を、コールセットのトラックごとに要約して返します。各トラックについて、bucket_size、bucket_count、観測された positions、対象位置の合計 target_positions、観測されなかった missing_positions も返されます。塩基が欠損している場合、コーラビリティは不明のままです。統計は返されたバケットのみを記述し、深度 0 を補って作成することはありません
• coverage_source で 1 つのトラック（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 に列挙されます
• 1 回の呼び出しで最大 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 を指定し、CANVAS_DEFAULT_ROW_LIMIT の上限（既定値は 10,000）を超えるには、SQL でフィルターまたは集計を行ってください
• 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} _リソース

• 1 つのバリアントの集団レコードを application/json 形式で返します。内容は gnomad_get_variant を反映します。variantId には染色体-位置-参照-代替 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 は必須（染色体-位置-参照-代替、または rsID。不正な形式は拒否されます）。gene と dataset は省略可能です。dataset には gnomad_r4、gnomad_r3、gnomad_r2_1、exac のいずれかを指定します。省略時はサーバーの既定値が適用されます
• 3 段階のチェーンを 1 つのユーザーメッセージとして出力します：集団頻度（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 を実行できます

エージェントに適した出力：

• 祖先集団ごとのアレル頻度ベクトルを完全な形で返し、単一の全体 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 では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

以下を 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 以上（または 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 req/s から 10 req/s に引き上げられます。	—
CANVAS_PROVIDER_TYPE	リストツールの背後で使われる、スピル／SQL パス用の DataCanvas バックエンドです。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を参照してください。