[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_128":129},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":49,"_69":70,"_71":72,"_73":74,"_75":76,"_77":78,"_79":-5,"_80":-5,"_81":-5,"_82":49,"_83":-5,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95,"_96":97},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","gnomad-genetics-mcp-server","@cyanheads/gnomad-genetics-mcp-server","displayName","gnomad genetics mcp server","tagline","Look up allele frequencies by ancestry, gene constraint, variants, and coverage over gnomAD.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://gnomad-genetics.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1783338798000,"updatedAt",1788778561000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fgnomad-genetics-mcp-server","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1788144043000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/cyanheads/gnomad-genetics-mcp-server","githubRepoFullName","cyanheads/gnomad-genetics-mcp-server","releaseId","ext-cyanheads-gnomad-genetics-mcp-server","version","0.2.1","descriptionMarkdown","

@cyanheads/gnomad-genetics-mcp-server

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.\n

7 Tools (+1 opt-in) • 2 Resources • 1 Prompt

\n\n

\n\n[![Version](https://img.shields.io/badge/Version-0.2.1-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/)\n\n

\n\n

\n\n[![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)\n\n[![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)\n\n

\n\n

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

\n\n---\n\n## Tools\n\nFive gnomAD tools, plus three for SQL analytics over the DuckDB-backed canvas tables the list tools materialize:\n\n| Tool | Description |\n|:---|:---|\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `gnomad_dataframe_query` | Run a read-only SQL `SELECT` across canvas tables staged by the list tools. |\n| `gnomad_dataframe_describe` | List the tables staged on a canvas and their columns before writing SQL. |\n| `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. |\n\n### `gnomad_get_variant`\n\nThe \"how common, is it benign\" answer in one call.\n\n- 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`)\n- Per-item partial success — a malformed or absent ID lands in `failed[]` without failing the others\n- Per-ancestry frequency vector is returned in full, never collapsed to a single global AF\n- 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\n- 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\n\n---\n\n### `gnomad_get_gene_constraint`\n\nThe orthogonal axis to allele frequency — a loss-of-function variant matters far more in a gene intolerant to being broken.\n\n- Accepts an HGNC symbol (`PCSK9`) or an Ensembl gene ID (`ENSG00000169174`)\n- 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\n- Many genes have null constraint (sparse upstream) — null fields are reported as such, never fabricated\n- `constraint_flags` surfaces v4 beta caveats flagged by the gnomAD team\n\n---\n\n### `gnomad_list_gene_variants`\n\nList variants across a gene, transcript, or region, then SQL the full set.\n\n- Supply exactly one of `gene`, `transcript_id`, or `region` (`chrom-start-stop`, 1-based inclusive)\n- Optional filters: one `consequence_class` (`lof` / `missense` / `synonymous` / `other`) and/or a maximum allele frequency\n- 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\n- Reusing a `canvas_id` REPLACES the staged table; it does not append\n- 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\n\n---\n\n### `gnomad_get_coverage`\n\nDisambiguate a true absent variant from an uncallable position.\n\n- Supply exactly one of `gene`, `transcript_id`, or `region`\n- Returns mean and median read depth plus the mean fraction of samples covered at each threshold (1× through 100×), summarized per callset track\n- `coverage_source` narrows to one track (`exome` / `genome`); omit to return every available track\n- A variant missing from a well-covered region is informative; one missing from a poorly-covered region is not\n\n---\n\n### `gnomad_search_clinvar`\n\nGene-panel curation depth beyond the per-variant ClinVar join, via NCBI E-utilities.\n\n- Returns a gene's classified ClinVar variants — clinical significance, review status with a 0–4 star rating, associated conditions, molecular consequences, and submission counts\n- Optional filters: `clinical_significance` (e.g. `pathogenic`) and a minimum star rating (`min_review_stars`, 0–4)\n- The full set is staged on the `clinvar_variants` canvas table with an inline preview; reusing a `canvas_id` REPLACES that table\n- Keyless, but honors `NCBI_API_KEY` for a higher rate limit (10 vs 3 req/s)\n\n---\n\n### Canvas dataframe tools\n\n`gnomad_dataframe_query`, `gnomad_dataframe_describe`, and `gnomad_dataframe_drop` operate on the canvas tables the list tools stage.\n\n- `gnomad_dataframe_query` runs single-statement `SELECT`s only — writes, DDL, and file/HTTP table functions are rejected by the canvas gate\n- `gnomad_dataframe_describe` returns each staged table's name, row count, and column schema — call it before writing SQL\n- `gnomad_dataframe_drop` is a deliberate mutation (`readOnlyHint: false`); it stays absent from `tools/list` unless `GNOMAD_DATAFRAME_DROP_ENABLED=true`\n- All three require `CANVAS_PROVIDER_TYPE=duckdb`; without it they return a `canvas_disabled` error\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `gnomad://variant/{dataset}/{variantId}` | Population record for one variant — mirrors `gnomad_get_variant`. The `dataset` segment keeps the URI self-describing. |\n| Resource | `gnomad://gene/{dataset}/{gene}/constraint` | Gene loss-of-function constraint — mirrors `gnomad_get_gene_constraint`. |\n| Prompt | `gnomad_variant_triage` | Guided rare-disease variant-triage workflow: population frequency → gene constraint → callability check, in order. |\n\nAll 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.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Typed error contracts with agent-facing recovery hints\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\ngnomAD-specific:\n\n- Single keyless GraphQL source for the entire core surface — ClinVar significance is joined per variant inside gnomAD's own response\n- `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\n- Polite client — conservative concurrency cap and exponential backoff against a community-funded, rate-limited API\n- In-conversation SQL analytics: `gnomad_list_gene_variants` and `gnomad_search_clinvar` stage their full result on a DuckDB-backed canvas table queryable via `gnomad_dataframe_query`\n\nAgent-friendly output:\n\n- Per-ancestry allele-frequency vector returned in full, never collapsed to a single global AF — the cross-ancestry contrast is the signal clinical interpretation needs\n- Graceful partial failure — `gnomad_get_variant` returns per-item `failed[]` rows with actionable messages instead of failing the whole batch\n- Provenance on every response — effective `dataset` and `reference_genome` echoed back; null upstream fields preserved as null, never fabricated\n- Recovery hints on errors (`incoherent_build`, `invalid_target`, `gene_not_found`, `canvas_disabled`) so callers know the next move\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://gnomad-genetics.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"gnomad-genetics-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://gnomad-genetics.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file. gnomAD is a free, keyless API — no credentials required.\n\n```json\n{\n \"mcpServers\": {\n \"gnomad-genetics-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/gnomad-genetics-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"gnomad-genetics-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/gnomad-genetics-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"gnomad-genetics-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/gnomad-genetics-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\nTo enable the SQL analytics path, also set `CANVAS_PROVIDER_TYPE=duckdb` (requires the `@duckdb/node-api` peer dependency; unavailable on Cloudflare Workers).\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key — gnomAD's GraphQL endpoint is keyless. An optional `NCBI_API_KEY` raises the `gnomad_search_clinvar` rate limit.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/gnomad-genetics-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd gnomad-genetics-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# all vars are optional — the server runs keyless out of the box\n```\n\n## Configuration\n\nAll variables are optional; the server runs keyless with the defaults below.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `GNOMAD_API_BASE_URL` | gnomAD GraphQL endpoint. Override for a private mirror or testing. | `https://gnomad.broadinstitute.org/api` |\n| `GNOMAD_DEFAULT_DATASET` | Dataset used when a tool call omits `dataset` (`gnomad_r4` / `gnomad_r3` / `gnomad_r2_1` / `exac`). | `gnomad_r4` |\n| `GNOMAD_REQUEST_TIMEOUT_MS` | Per-request timeout against the GraphQL endpoint, in milliseconds. | `30000` |\n| `GNOMAD_MAX_CONCURRENCY` | Cap on concurrent upstream requests — politeness against a community-funded API. | `2` |\n| `GNOMAD_MAX_VARIANT_BATCH` | Maximum variant IDs accepted per `gnomad_get_variant` call. | `25` |\n| `CLINVAR_BASE_URL` | NCBI E-utilities base URL for `gnomad_search_clinvar`. | `https://eutils.ncbi.nlm.nih.gov/entrez/eutils` |\n| `NCBI_API_KEY` | Optional NCBI key. Raises the E-utilities rate limit from 3 to 10 req/s. | — |\n| `CANVAS_PROVIDER_TYPE` | Set to `duckdb` to enable the spill/SQL path behind the list tools. When `none`, they return a capped inline preview. | `none` |\n| `GNOMAD_DATAFRAME_DROP_ENABLED` | Gate for the opt-in `gnomad_dataframe_drop` tool. Off by default. | `false` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](https://github.com/cyanheads/gnomad-genetics-mcp-server/blob/main/.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t gnomad-genetics-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 gnomad-genetics-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/gnomad-genetics-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools/resources/prompts and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) and shared input schemas. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |\n| `src/mcp-server/prompts` | Prompt definitions (`*.prompt.ts`). |\n| `src/services/gnomad` | gnomAD GraphQL client, query documents, and domain types. |\n| `src/services/clinvar` | NCBI E-utilities client for the optional ClinVar tool. |\n| `src/services/canvas-accessor.ts` | Module-level accessor for the framework's optional DataCanvas. |\n\n## Development guide\n\nSee [`CLAUDE.md`/`AGENTS.md`](https://github.com/cyanheads/gnomad-genetics-mcp-server/blob/main/CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources in the `createApp()` arrays in `src/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/cyanheads/gnomad-genetics-mcp-server/blob/main/LICENSE) for details.\n\ngnomAD data is provided by the [Genome Aggregation Database](https://gnomad.broadinstitute.org) (Broad Institute). ClinVar data is provided by [NCBI](https://www.ncbi.nlm.nih.gov/clinvar/).\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[100,101,102,19,103,104,105,106,107,108],"assets",[],"stats",{"_98":85,"_99":85},"ratingAvg","reviewCount","allele-frequency","bioinformatics","clinvar","gene-constraint","genetics","genomics","gnomad","typescript","variant-interpretation","topics",[100,101,102,19,103,104,105,106,126,127,107,108],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/gnomad-genetics-mcp-server","homepage","https://www.npmjs.com/package/@cyanheads/gnomad-genetics-mcp-server","packages",[121,122],{"_123":124,"_125":22,"_75":76},{"_123":124,"_125":22,"_75":76},"registryType","npm","identifier","mcp","model-context-protocol","ENV",{"_130":131,"_132":133,"_134":135},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]