gnomad-genetics-mcp-server

<div align="center">
  <h1>@cyanheads/gnomad-genetics-mcp-server</h1>
  <p><b>Look up variant allele frequencies by ancestry, gene loss-of-function constraint, gene variant lists, and sequencing coverage over gnomAD — with ClinVar significance joined in — via MCP. STDIO or Streamable HTTP.</b>
  <div>7 Tools (+1 opt-in) • 2 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/gnomad-genetics-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/gnomad-genetics-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gnomad-genetics-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/gnomad-genetics-mcp-server/releases/latest/download/gnomad-genetics-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gnomad-genetics-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZ25vbWFkLWdlbmV0aWNzLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22gnomad-genetics-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fgnomad-genetics-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://gnomad-genetics.caseyjhand.com/mcp](https://gnomad-genetics.caseyjhand.com/mcp)

</div>

---

## Tools

Five gnomAD tools, plus three for SQL analytics over the DuckDB-backed canvas tables the list tools materialize:

| Tool | Description |
|:---|:---|
| `gnomad_get_variant` | Full population record for one or more variants — AC/AN/AF overall and per genetic-ancestry group, homozygote/hemizygote counts, quality flags, transcript consequence, in-silico predictors, and joined ClinVar significance. Batch up to 25 IDs with per-item partial success. |
| `gnomad_get_gene_constraint` | Gene loss-of-function constraint — pLI, LOEUF (`oe_lof_upper`) with CI, observed/expected ratios, and Z-scores. By HGNC symbol or Ensembl gene ID. |
| `gnomad_list_gene_variants` | Every variant in a gene, transcript, or region with allele frequencies and predicted consequences, filterable by consequence class and max AF. Spills to the `gene_variants` canvas table. |
| `gnomad_get_coverage` | Sequencing coverage across a gene, transcript, or region — mean/median depth and the fraction of samples over depth thresholds, per callset track. Tells a true absent variant from an uncallable position. |
| `gnomad_search_clinvar` | Gene-level ClinVar detail via NCBI E-utilities — classified variants, review status (star rating), conditions, and submission counts. Spills to the `clinvar_variants` canvas table. |
| `gnomad_dataframe_query` | Run a read-only SQL `SELECT` across canvas tables staged by the list tools. |
| `gnomad_dataframe_describe` | List the tables staged on a canvas and their columns before writing SQL. |
| `gnomad_dataframe_drop` | Drop a named table from a canvas to reclaim memory. Opt-in via `GNOMAD_DATAFRAME_DROP_ENABLED=true` — off by default since per-table TTL already handles cleanup. |

### `gnomad_get_variant`

The "how common, is it benign" answer in one call.

- Batch up to 25 IDs per call, each a `chrom-pos-ref-alt` variantId (e.g. `1-55051215-G-GA`) or an rsID (e.g. `rs11591147`)
- Per-item partial success — a malformed or absent ID lands in `failed[]` without failing the others
- Per-ancestry frequency vector is returned in full, never collapsed to a single global AF
- Reports which callset(s) (`exome` / `genome`) carry the variant, quality flags, transcript consequence, in-silico predictor scores, and the ClinVar significance gnomAD joins per variant
- An empty `found[]` for a well-formed ID means the variant is not in the chosen dataset — pair with `gnomad_get_coverage` to confirm the position is callable before concluding true absence

---

### `gnomad_get_gene_constraint`

The orthogonal axis to allele frequency — a loss-of-function variant matters far more in a gene intolerant to being broken.

- Accepts an HGNC symbol (`PCSK9`) or an Ensembl gene ID (`ENSG00000169174`)
- Returns pLI (>0.9 intolerant), LOEUF / `oe_lof_upper` (<0.6 intolerant in v4, <0.35 in v2) with its lower bound, observed/expected ratios for LoF / missense / synonymous, and the three Z-scores
- Many genes have null constraint (sparse upstream) — null fields are reported as such, never fabricated
- `constraint_flags` surfaces v4 beta caveats flagged by the gnomAD team

---

### `gnomad_list_gene_variants`

List variants across a gene, transcript, or region, then SQL the full set.

- Supply exactly one of `gene`, `transcript_id`, or `region` (`chrom-start-stop`, 1-based inclusive)
- Optional filters: one `consequence_class` (`lof` / `missense` / `synonymous` / `other`) and/or a maximum allele frequency
- The full result is staged on a DataCanvas table named `gene_variants` with an inline preview returned alongside `canvas_id` and `table_name` — query it with `gnomad_dataframe_query` to rank by AF, count by consequence, or group across the complete set
- Reusing a `canvas_id` REPLACES the staged table; it does not append
- When the canvas is disabled (`CANVAS_PROVIDER_TYPE` != `duckdb`) the tool returns a capped inline preview with `spilled=false` and the SQL path is unavailable

---

### `gnomad_get_coverage`

Disambiguate a true absent variant from an uncallable position.

- Supply exactly one of `gene`, `transcript_id`, or `region`
- Returns mean and median read depth plus the mean fraction of samples covered at each threshold (1× through 100×), summarized per callset track
- `coverage_source` narrows to one track (`exome` / `genome`); omit to return every available track
- A variant missing from a well-covered region is informative; one missing from a poorly-covered region is not

---

### `gnomad_search_clinvar`

Gene-panel curation depth beyond the per-variant ClinVar join, via NCBI E-utilities.

- Returns a gene's classified ClinVar variants — clinical significance, review status with a 0–4 star rating, associated conditions, molecular consequences, and submission counts
- Optional filters: `clinical_significance` (e.g. `pathogenic`) and a minimum star rating (`min_review_stars`, 0–4)
- The full set is staged on the `clinvar_variants` canvas table with an inline preview; reusing a `canvas_id` REPLACES that table
- Keyless, but honors `NCBI_API_KEY` for a higher rate limit (10 vs 3 req/s)

---

### Canvas dataframe tools

`gnomad_dataframe_query`, `gnomad_dataframe_describe`, and `gnomad_dataframe_drop` operate on the canvas tables the list tools stage.

- `gnomad_dataframe_query` runs single-statement `SELECT`s only — writes, DDL, and file/HTTP table functions are rejected by the canvas gate
- `gnomad_dataframe_describe` returns each staged table's name, row count, and column schema — call it before writing SQL
- `gnomad_dataframe_drop` is a deliberate mutation (`readOnlyHint: false`); it stays absent from `tools/list` unless `GNOMAD_DATAFRAME_DROP_ENABLED=true`
- All three require `CANVAS_PROVIDER_TYPE=duckdb`; without it they return a `canvas_disabled` error

## Resources and prompts

| Type | Name | Description |
|:---|:---|:---|
| Resource | `gnomad://variant/{dataset}/{variantId}` | Population record for one variant — mirrors `gnomad_get_variant`. The `dataset` segment keeps the URI self-describing. |
| Resource | `gnomad://gene/{dataset}/{gene}/constraint` | Gene loss-of-function constraint — mirrors `gnomad_get_gene_constraint`. |
| Prompt | `gnomad_variant_triage` | Guided rare-disease variant-triage workflow: population frequency → gene constraint → callability check, in order. |

All resource data is also reachable via tools. The list tools (`gnomad_list_gene_variants`, `gnomad_get_coverage`, `gnomad_search_clinvar`) return analytical row sets rather than stable single-URI documents, so they are not exposed as resources — call the tools instead.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Typed error contracts with agent-facing recovery hints
- Pluggable auth: `none`, `jwt`, `oauth`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

gnomAD-specific:

- Single keyless GraphQL source for the entire core surface — ClinVar significance is joined per variant inside gnomAD's own response
- `dataset` and `reference_genome` are distinct, coherence-validated parameters (v4/v3 ⇒ GRCh38, v2.1/ExAC ⇒ GRCh37); both are echoed in every tool's output so a wrong-build coordinate mismatch is visible
- Polite client — conserv