koido/gnomad-mcp
If you are the rightful owner of gnomad-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The gnomAD MCP Server provides a programmatic interface to the Genome Aggregation Database API, supporting multiple API versions and abstracting version-specific differences.
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.
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.18fastmcp >= 2.2.1gql >= 3.5.2httpx >= 0.28.1mcp[cli] >= 1.6.0nest-asyncio >= 1.6.0pytest >= 8.3.5pytest-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
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 and
- 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 file for details.
This project uses the gnomAD API. Please ensure you cite gnomAD when using this tool or its outputs.
