Variant¶
Use variant commands for compact annotation, source-backed interpretation context, and optional predictive and population-genetics sections.
Accepted variant identifiers¶
BioMCP supports multiple input forms:
- rsID:
rs113488022 - HGVS genomic:
chr7:g.140453136A>T - gene-protein form:
BRAF V600E,BRAF p.Val600Glu
These exact formats are accepted by biomcp get variant and the exact-ID
helper commands.
Search variants¶
By gene and protein change:
biomcp search variant -g BRAF --hgvsp V600E --limit 5
biomcp search variant -g BRAF --hgvsp p.Val600Glu --limit 5
biomcp search variant BRAF p.Val600Glu --limit 5
By residue alias shorthand:
By protein shorthand when gene context is already supplied:
Standalone protein shorthand like R620W returns variant-specific recovery
guidance instead of falling back to gene or condition discovery.
By significance:
With population and score filters:
Get a variant record¶
biomcp get variant rs113488022
biomcp get variant "chr7:g.140453136A>T"
biomcp get variant "BRAF V600E"
biomcp get variant "BRAF p.Val600Glu"
The default output favors concise, clinically relevant context first.
When BioMCP can derive a compact literature-facing alias, variant search rows
and detail cards also show Legacy Name, and JSON output includes
legacy_name.
Shorthand such as PTPN22 620W or R620W is not treated as an exact variant
ID. Use biomcp search variant for those inputs.
Normalize transcript HGVS¶
Use the explicit normalization proxy when you already have a transcript HGVS string and want source-labelled output from Mutalyzer and VariantValidator:
biomcp variant normalize all NM_000248.3:c.135del
biomcp variant normalize all 'NM_004448.2:c.829G>T'
biomcp variant normalize mutalyzer NM_000248.3:c.135del
biomcp variant normalize variantvalidator 'NM_004448.2:c.829G>T'
JSON output always writes a parseable object on exit 0. It preserves the submitted
input, an aggregate status, a results list of normalized forms, a message,
one result per service with each service status, source-returned
transcript/normalized/genomic/protein fields, warnings such as VariantValidator
TranscriptVersionWarning, and _meta.next_commands. When no provider returns a
normalized form, status is no_result and results is an empty list. Markdown
VariantValidator genomic descriptions are labeled as GRCh38 because BioMCP calls
VariantValidator's GRCh38 normalization endpoint.
This helper does not parse messy report prose, does not choose, select, guess, or infer transcripts, and does not classify variants or provide clinical interpretation/clinical meaning.
Request variant sections¶
The default variant card includes a one-line therapeutic-evidence pointer. When
cached MyVariant CIViC evidence is already in the fetched variant payload, the
line reports the cached predictive-item count and points to get variant <id>
civic; otherwise it prints the bare get variant <id> civic next-command. The
default card does not run the live CIViC GraphQL section call.
Prediction section:
ClinVar-focused section:
ClinVar JSON also exposes top_disease when condition aggregation is available,
reusing the highest-ranked ClinVar condition row already shown in the section.
The runtime See also: block is significance-aware: pathogenic or likely
pathogenic variants keep the gene and drug-target pivots near the top, while
VUS / uncertain-significance variants add a literature search anchored by the
variant alias and any available disease context before the generic drug-target
fallback.
Population section:
Population JSON exposes additive compact frequency fields:
allele_frequency_raw and allele_frequency_percent. Markdown keeps the raw
gnomAD AF line and appends the compact percent inline.
CIViC section:
The CIViC section includes cached MyVariant rows plus live GraphQL context when available. It also carries a currency caveat and points to literature and drug cross-check commands because curated CIViC evidence can lag current standard of care.
GWAS section (trait associations from GWAS Catalog):
GWAS JSON exposes supporting_pmids as an ordered, deduplicated array when the
section loads successfully. null means either the GWAS section was not loaded
or GWAS Catalog was temporarily unavailable. In the unavailable case, JSON also
includes gwas_unavailable_reason with a source-specific message.
Predictions (aggregated prediction scores):
Conservation (GERP, phyloP):
COSMIC (somatic mutation data):
CGI (Cancer Genome Interpreter annotations):
cBioPortal (frequency data):
Cancerhotspots.org recurrence counts are loaded by all for exact gene/protein
queries such as BRAF V600E. JSON includes cancerhotspots.source,
matched_transcript, position_count (residue-level tumorCount), and
same_aa_count (the exact alternate amino acid count). If the lookup succeeds
but the residue/change is not a cancerhotspots hotspot, those count/provenance
fields are present as JSON null under the source-labelled object; upstream
unavailability omits the object instead of emitting zeros.
All supported sections:
all includes broad source-backed annotation sections such as ClinVar,
population, conservation, expanded MyVariant prediction scores, cBioPortal,
Cancerhotspots.org, CIViC, CGI, COSMIC, and GWAS. It does not run the
AlphaGenome predict section because that path requires ALPHAGENOME_API_KEY;
request predict explicitly when you want AlphaGenome output.
Helper commands¶
biomcp variant trials "BRAF V600E" # search trials mentioning this mutation
biomcp variant articles "BRAF V600E" # search PubMed/PubTator for this variant
biomcp variant structure "BRAF V600E" # residue/domain/PDB/AlphaFold/hotspot context
biomcp variant oncokb "BRAF V600E" # OncoKB lookup (requires ONCOKB_TOKEN)
variant structure is an opt-in, network-backed helper. JSON includes the selected
residue, matched HGVSp aliases, other MyVariant/dbNSFP positions, overlapping
InterPro domain ranges, typed UniProt PDB rows, an AlphaFold URL,
Cancerhotspots recurrence, warnings, and _meta.next_commands. It does not add
structure data to default get variant output.
variant articles uses PubTator variant annotations when BioMCP can resolve a
confident variant entity. If annotation recall is unavailable, the output labels
the route as a best-effort free-text fallback so agents know which recall path
was used.
Search GWAS associations¶
By gene:
By trait:
Trait search uses GWAS Catalog trait endpoints first, then study-association fallback paths when needed.
Optional enrichment¶
Variant base output may include cBioPortal enrichment when available.
OncoKB is accessed explicitly via biomcp variant oncokb "<gene> <variant>" and requires ONCOKB_TOKEN.
Prediction requirements¶
Prediction sections may require ALPHAGENOME_API_KEY depending on source path.
Unsupported inputs are surfaced with explicit validation messages.
JSON mode¶
biomcp --json get variant "BRAF V600E"
biomcp --json get variant rs7903146 gwas
biomcp --json search gwas --trait "type 2 diabetes"
Practical tips¶
- Use
search variantfirst for shorthand or ambiguous inputs. - Start with the base card, then add source sections such as
clinvar,civic, orpopulationonly when needed. - Use
allwhen you need a one-shot export for review or downstream comparison.