README.md
Programmatic interface to the Genome Aggregation Database (gnomAD) API
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 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](LICENSE
Tools (5)
get_gene_infoRetrieve gene metadata and constraint metrics by gene_id or gene_symbol.get_variant_infoRetrieve variant metadata and population frequency data by variantId.get_clinvar_variant_infoRetrieve ClinVar variant data and clinical significance.search_for_genesSearch for genes by symbol or name.search_for_variantsSearch for variants by ID, gene, or region.Configuration
claude_desktop_config.json
{"mcpServers": {"gnomad": {"command": "uv", "args": ["--directory", "where you cloned the repo", "run", "server.py"], "env": {}}}}Try it
āSearch for the gene BRCA1 and retrieve its metadata and constraint metrics.
āGet variant information for the variant ID rs123456789.
āFind clinical significance data for the variant associated with ClinVar ID 12345.
āSearch for genes related to the symbol 'TP53'.