gnomad-genetics-mcp-server: search clinvar
gnomad_search_clinvarSearch ClinVar (NCBI E-utilities) for a gene and return its classified variants — the germline clinical significance with its review status, 0–4 star rating, and conditions; any somatic oncogenicity or clinical-impact classification with its own review status and tumor types; molecular consequences, submission counts, and gnomAD-compatible identifiers (canonical SPDI, rsIDs, and a GRCh38 variant ID for gnomad_get_variant, derived from the SPDI or filled from gnomAD's own ClinVar mapping) — turning the variant-level significance gnomAD joins into a gene-panel curation view. Optionally filter by germline clinical_significance (e.g. pathogenic) and a minimum germline star rating. Each call returns one window of up to limit ClinVar records (default 10): total_found is the ClinVar count for the search terms (the match count for a mapped significance term alone, a candidate count once min_review_stars or any other term applies), and next_offset continues through the rest via offset. A window too large to inline is staged on a DataCanvas table named clinvar_variants, returned as canvas_id and table_name beside an inline preview — call gnomad_dataframe_describe for its columns, then gnomad_dataframe_query to rank or count across the window. A window that fits inline stages no table unless canvas_id is supplied. Keyless, but honors NCBI_API_KEY for a higher rate limit. Credit: ClinVar, NCBI.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"gene": "<gene>"
},
"name": "gnomad_search_clinvar"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gene | Yes | Gene HGNC symbol (e.g. PCSK9). ClinVar indexes HGNC symbols only — Ensembl gene IDs (ENSG…) are not resolved here, unlike the other gnomAD tools; resolve one to its symbol via ensembl_lookup_gene. | |
| limit | No | ClinVar records to fetch in this window. A mapped clinical_significance term alone narrows the search to matching records, so its windows are full; min_review_stars and any other significance term are also applied after the fetch, so their windows can return fewer rows. Default 10; a value above 1,500 is clamped to 1,500, with a notice. | |
| offset | No | Zero-based position of the first ClinVar record in this window. Pass next_offset from the previous call to continue. | |
| canvas_id | No | Optional canvas ID from a prior call, to reuse the same canvas. When supplied, each search writes its window to the clinvar_variants table on that canvas, replacing (not appending to) the previous one — even when the window fits inline; a window with no rows removes the table. An Ensembl gene ID searches nothing and leaves the canvas as it was. Omit to stage on a fresh canvas only when the window is too large to inline. | |
| min_review_stars | No | Keep only variants whose germline classification has at least this gold-star rating (0–4). ClinVar's review-status search also matches the review status of a somatic classification, and those records are dropped after the fetch, so a window can return fewer rows than limit. | |
| clinical_significance | No | Filter by ClinVar germline classification, case-insensitive, matched as whole words; underscores read as spaces. Somatic oncogenicity and clinical-impact classifications are never matched. pathogenic (Pathogenic and Likely pathogenic, combined and low-penetrance forms included), likely pathogenic, uncertain significance, vus (Uncertain significance plus VUS-high, VUS-mid, and VUS-low), likely benign, benign (Benign and Likely benign), and conflicting search ClinVar's germline classification index, so on their own their windows hold matching records only. Any other term (e.g. risk factor) narrows a text search, and its windows can return fewer rows than limit. Blank means no filter. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gene | No | The gene searched, as given. | |
| error | No | Present when the call failed. Absent on success. | |
| total | No | Rows in this window that passed the filters, including any beyond the preview. | |
| notice | No | Guidance on a clamped limit, completeness (the offset that continues the list, or an offset past the end), no-match results, the staged table with its next steps (gnomad_dataframe_describe, then gnomad_dataframe_query), gnomAD's ClinVar mapping when it could not fill missing grch38_variant_id values, and which identifier to pass to gnomad_get_variant. | |
| filters | No | Row filters applied to this window; offset and limit are not filters. | |
| preview | No | Inline preview rows — the immediate answer; the window's every row unless spilled. | |
| spilled | No | True when this window's rows exceeded the inline preview budget, so the preview holds only the first rows and table_name holds them all. | |
| canvas_id | No | Canvas holding table_name (or the canvas_id you supplied) — pass it to gnomad_dataframe_describe, then gnomad_dataframe_query. Empty when this call used no canvas: the window fit inline and no canvas_id was supplied, the gene was an Ensembl ID (nothing was searched), or the canvas is disabled. | |
| truncated | No | True when ClinVar records remain past this window; continue with next_offset. | |
| table_name | No | Canvas table this call staged (clinvar_variants), holding this window's rows — inspect it with gnomad_dataframe_describe, then query it with gnomad_dataframe_query. Empty when this call staged no table. | |
| next_offset | No | offset for the next window; null when this window reaches the end. | |
| total_found | No | ClinVar records matching the gene and filter terms across every window, counted by the search before the post-fetch filters: the match count for a mapped significance term alone, a candidate count once min_review_stars or any other term applies. | |
| unavailable_ids | No | VariationIDs in this window that ClinVar returned no summary for, so they have no row; empty when none. |