How do I use gnomAD MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gnomAD MCP Server show me population frequencies for variant 12-120931006-G-A in v4" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

gnomAD MCP Server

by koido

Overview Schema Source Related Servers Discussions Admin

Python

Remote

gnomAD MCP Server

Overview

This MCP server provides a programmatic interface to the Genome Aggregation Database (gnomAD) API, supporting multiple API versions (v2.1.1, v3.1.2, v4.1.0).
It abstracts version-specific field and schema differences, exposing a unified API for downstream tools and users.

Related MCP server: UCSC Genome Browser MCP Server

Status

🚧 Under Active Development 🚧

This project is under active development. APIs and features may change without notice.

Supported gnomAD API Versions

v4.1.0 (gnomad_r4)
v3.1.2 (gnomad_r3)
v2.1.1 (gnomad_r2_1)

Supported Queries by Version

The following table summarizes which queries are available for each gnomAD API version:

Query Type	Description	v2	v3	v4
get_gene_info	Retrieve gene metadata and constraint metrics (direct lookup by gene_id/gene_symbol)	❌	❌	✅
get_region_info	Retrieve variant and summary information for a genomic region	❌	❌	✅
get_variant_info	Retrieve variant metadata and population frequency data (by variantId)	✅	✅	✅
get_clinvar_variant_info	Retrieve ClinVar variant data and clinical significance	✅	✅	✅
get_mitochondrial_variant_info	Retrieve mitochondrial variant data and population frequencies	❌	❌	✅
get_structural_variant_info	Retrieve structural variant (SV) data and population frequencies	✅	❌	✅
get_copy_number_variant_info	Retrieve copy number variant (CNV) data and population frequencies	❌	❌	✅
search_for_genes	Search for genes by symbol or name (no direct gene_id lookup in v2/v3)	✅	✅	✅
search_for_variants	Search for variants by ID, gene, or region	✅	✅	✅
get_str_info	Retrieve short tandem repeat (STR) data and population frequencies	❌	❌	✅
get_all_strs	Retrieve all STRs in the dataset	❌	❌	✅
get_variant_liftover	Retrieve liftover mapping for a variant between genomes	✅	❌	❌
get_metadata	Retrieve gnomAD browser metadata and API version info	✅	✅	✅

✅ = Supported in this version
❌ = Not supported in this version

Dependencies

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

Directory Structure

.
├── 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

Setup

Install dependencies

uv sync

Activate the virtual environment

. .venv/bin/activate

Test the server

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

Add the MCP server to your MCP server list (Claude, Cursor, etc.)

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

Run tests

Please see README_tests.md

Query & API Design

Uses the QueryTemplateEngine pattern to manage version-specific GraphQL query templates.
Currently, queries are fixed; see (./gnomad/queries)
- The queries were obtained using schema_fetcher.py and schema_analyzer.py
- TODO: Dynamic queries
MCP tool endpoints are documented with detailed parameter and output descriptions.

License

This MCP server itself is licensed under the Apache License 2.0 - see the LICENSE file for details.

This project uses the gnomAD API. Please ensure you cite gnomAD when using this tool or its outputs.

Acknowledgements

Available Tools

12 tools

get_clinvar_variant_infoB

[gnomAD API] Retrieve ClinVar variant info (v2/v3/v4) Args: dataset (str): gnomAD dataset ID (gnomad_r4/gnomad_r3/gnomad_r2_1) reference_genome (str): Reference genome (GRCh37 or GRCh38) variant_id (str): Variant ID Returns: dict: ClinVar info

Inputs: dataset (required), reference_genome (required), variant_id (required). Returns: object

get_copy_number_variant_infoB

[gnomAD API] Retrieve copy number variant info (v4 only) Args: reference_genome (str): Reference genome (GRCh38) variantId (str): CNV ID (e.g. 18714__DUP) Returns: dict: CNV info Note: Not supported in v2/v3.

Inputs: reference_genome (required), variantId (required), dataset. Returns: object

get_gene_infoB

[gnomAD API] Retrieve gene information (v4 only) Args: gene_id (str, optional): Ensembl gene ID (e.g. ENSG00000139618) gene_symbol (str, optional): Gene symbol (e.g. PCSK9) Returns: dict: gene info Note: Not supported in v2/v3. Use search_for_genes instead.

Inputs: gene_id, gene_symbol, dataset, reference_genome. Returns: object

get_metadataC

[gnomAD API] Retrieve metadata (v2/v3/v4) Args: dataset (str): gnomAD dataset ID (gnomad_r4/gnomad_r3/gnomad_r2_1) Returns: dict: metadata

Inputs: dataset (required), reference_genome (required). Returns: object

get_mitochondrial_variant_infoA

[gnomAD API] Retrieve mitochondrial variant info (v4 only) Args: reference_genome (str): Reference genome (GRCh37 or GRCh38) variant_id (str): Mitochondrial variant ID (e.g. M-8602-T-C). Build must be GRCh38. Returns: dict: mito variant info Note: Not supported in v2/v3.

Inputs: reference_genome (required), variant_id (required), dataset. Returns: object

get_region_infoC

[gnomAD API] Retrieve region information (v4 only) Args: reference_genome (str): Reference genome (GRCh38) chrom (str): Chromosome start (int): Start position. Build must be GRCh38. stop (int): End position. Build must be GRCh38. Returns: dict: region info Note: Not supported in v2/v3.

Inputs: reference_genome (required), chrom (required), start (required), stop (required), +1 more. Returns: object

get_str_infoB

[gnomAD API] Retrieve STR info (v4 only) Args: reference_genome (str): Reference genome (GRCh38) id (str): STR ID (e.g. ATXN1) Returns: dict: STR info Note: Not supported in v2/v3.

Inputs: reference_genome (required), id (required), dataset. Returns: object

get_structural_variant_infoC

[gnomAD API] Retrieve structural variant info (v2/v4) Args: dataset (str): SV dataset ID (gnomad_sv_r4/gnomad_sv_r2_1) reference_genome (str): Reference genome (GRCh37 or GRCh38) variantId (str): Structural variant ID Returns: dict: SV info

Inputs: dataset (required), reference_genome (required), variantId (required). Returns: object

get_variant_infoC

[gnomAD API] Retrieve variant information (v2/v3/v4) Args: dataset (str): gnomAD dataset ID (gnomad_r4/gnomad_r3/gnomad_r2_1) reference_genome (str): Reference genome (GRCh37 or GRCh38) variantId (str): Variant ID (e.g. 1-55051215-G-GA) Returns: dict: variant info

Inputs: dataset (required), reference_genome (required), variantId (required). Returns: object

get_variant_liftoverB

[gnomAD API] Retrieve liftover info (v2 only) Args: reference_genome (str): Reference genome (GRCh37 or GRCh38) source_variant_id (str, optional): Source variant ID (e.g. 12-112241766-G-A on GRCh37) liftover_variant_id (str, optional): Lifted over variant ID (e.g. 12-111803962-G-A on GRCh38) Returns: dict: liftover info Note: Not supported in v3/v4.

Inputs: reference_genome (required), source_variant_id, liftover_variant_id, dataset. Returns: object

search_for_genesC

[gnomAD API] Search for genes (v2/v3/v4) Args: dataset (str): gnomAD dataset ID (gnomad_r3/gnomad_r2_1) reference_genome (str, optional): Reference genome (GRCh37 or GRCh38) query (str): Search string Returns: dict: search results

Inputs: dataset (required), reference_genome (required), query (required). Returns: object

search_for_variantsB

[gnomAD API] Search for variants (v2/v3/v4) Args: dataset (str): gnomAD dataset ID (gnomad_r4/gnomad_r3/gnomad_r2_1) reference_genome (str): Reference genome (GRCh37 or GRCh38) query (str): Search string (variant_id) Returns: dict: search results (variant_id)

Inputs: dataset (required), reference_genome (required), query (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-04-13 13:45 across 12 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific genomic data types (ClinVar variants, copy number variants, genes, metadata, mitochondrial variants, regions, STRs, structural variants, general variants, liftover, gene search, variant search). The descriptions clearly differentiate what each tool retrieves, with no apparent overlap in functionality.

Naming Consistency4/5

Most tools follow a consistent 'get_*_info' or 'search_for_*' pattern, but there are minor deviations: 'get_copy_number_variant_info' uses 'variantId' while 'get_variant_info' uses 'variantId' (both camelCase), and 'get_structural_variant_info' uses 'variantId' while others use 'variant_id' (snake_case). The overall pattern is clear and readable despite these inconsistencies.

Tool Count5/5

12 tools is well-scoped for a genomic database API server covering multiple data types (variants, genes, regions, etc.) across different gnomAD versions. Each tool serves a specific purpose in retrieving different genomic entities, with no obvious redundancy.

Completeness4/5

The toolset provides comprehensive retrieval capabilities for the gnomAD domain, covering all major genomic data types with both specific lookup and search functionality. The only minor gap is the version compatibility limitations noted in tool descriptions (some tools only work with specific gnomAD versions), but agents can work around this by checking metadata or using alternative tools.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

gnomad-genetics-mcp-serverA
io.github.cyanheads
Ancestry allele frequencies, LoF constraint, variant lists, and coverage from gnomAD, with ClinVar.
Bioinformatics Biology & Medicine
811
https://gnomad-genetics.caseyjhand.com/mcp
GnomadA
io.github.pipeworx-io
gnomAD MCP — Broad Institute Genome Aggregation Database (GraphQL).
Bioinformatics Biology & Medicine
492
https://gateway.pipeworx.io/gnomad/mcp
GeneBeA
net.genebe
Annotate and classify human genetic variants with GeneBe (ACMG, gnomAD, ClinVar). Research use only.
Bioinformatics Biology & Medicine
61
https://mcp.genebe.net/v1/mcp
pharmacogenomics-guidelines-mcp-serverA
io.github.cyanheads
Find pharmacogenomics guidelines, translate diplotypes, and retrieve prescribing recommendations.
Biology & Medicine Bioinformatics
611
https://pharmacogenomics-guidelines.caseyjhand.com/mcp

Related MCP Servers

gnomAD MCP Server
Bioinformatics Research & Data
shukwong
A
license
B
quality
D
maintenance
Enables AI assistants to query genetic variant data, gene constraints, and population genetics information from the gnomAD (Genome Aggregation Database) through its GraphQL API. Supports searching for genes and variants, retrieving constraint scores, analyzing population frequencies, and accessing genomic coverage data.
Updated a year ago (2025-08-13 20:36 UTC)
9
10
MIT
UCSC Genome Browser MCP Server
Bioinformatics Research & Data Biology & Medicine
hlydecker
A
license
B
quality
D
maintenance
Provides comprehensive access to the UCSC Genome Browser API, enabling queries of genomic data, DNA sequences, gene annotations, variants, and metadata across multiple species and assemblies.
Updated a year ago (2025-11-13 04:06 UTC)
12
7
MIT
EVEE MCP Server
Biology & Medicine Research & Data AI & Machine Learning
goodfire-ai
F
license
A
quality
D
maintenance
Provides interpretable variant effect predictions for 4.2 million ClinVar variants using the EVEE API. Enables searching, comparing, and analyzing genetic variants with AI-generated mechanistic interpretations and disruption profiles.
Updated 6 months ago (2026-05-20 21:30 UTC)
6
18
-
genefoundry
Bioinformatics Research & Data
berntpopp
A
license
Not graded
quality
B
maintenance
Federates 13 gene-related MCP backends (gnomAD, GTEx, etc.) behind a single Streamable HTTP endpoint with collision-free namespacing and search-based tool discovery.
Updated 2 days ago (2026-11-12 07:42 UTC)
7
MIT

gnomAD MCP Server

Overview

Status

Supported gnomAD API Versions

Supported Queries by Version

Dependencies

Directory Structure

Setup

Install dependencies

Activate the virtual environment

Test the server

Add the MCP server to your MCP server list (Claude, Cursor, etc.)

Run tests

Query & API Design

License

Acknowledgements

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

gnomAD MCP Server

UCSC Genome Browser MCP Server

EVEE MCP Server

genefoundry