biomcp

BioMCP CLI

If you don't know how to start, run biomcp suggest "<question>" first, then open the returned biomcp skill <slug> playbook for the full workflow.

Routing rules

• Start with the narrowest command that matches the question.
• Use biomcp discover "<free text>" when you only have a single biomedical phrase and need the CLI to resolve the first typed command. discover is a single-entity resolver and single-entity free-text lookup only: use it to resolve the canonical name, ID, or category of one thing. It is not a relational query tool and not a list-question seed. Examples: biomcp discover BRCA1 and biomcp discover dabigatran. Symptom-of-disease prompts, HPO symptom bridges, treatment prompts, gene+disease orientation, and unambiguous gene-plus-topic follow-ups remain supported exceptions.
• Relational or multi-entity questions may redirect to biomcp search all --keyword "<query>" instead of surfacing weak collocation matches as if they were a resolved discover answer.
• Use biomcp search all --gene <gene> --disease "<disease>" when you know the entities but not the next pivot.
• Treatment questions: biomcp search drug --indication "<disease>" --limit 5
• Diagnostic-test questions: use structured pivots first with biomcp get gene <symbol> diagnostics or biomcp get disease "<disease>" diagnostics; use biomcp list diagnostic for the full source/filter/section contract; use biomcp search diagnostic --gene <symbol> --limit 5, biomcp search diagnostic --disease "<disease>" --source all --limit 5, or biomcp get diagnostic <id> when you need the full search/detail surface.
• Symptom or phenotype questions: biomcp get disease <name_or_id> phenotypes
• Gene-function questions: biomcp get gene <symbol>
• Drug-safety questions: biomcp drug adverse-events <name> and biomcp get drug <name> safety
• Drug-interaction questions: biomcp drug interactions <name> and biomcp get drug <name> interactions
• EMA and WHO regional drug data are local runtime files that auto-download on first use, DDInter is the local drug-interaction bundle, CDC CVX/MVX is the companion local vaccine-brand bridge for default/EU vaccine searches plus explicit WHO vaccine search, and GTR plus WHO IVD are local diagnostic-test backbones; run biomcp ddinter sync, biomcp ema sync, biomcp who sync, biomcp cvx sync, biomcp gtr sync, or biomcp who-ivd sync to force-refresh before freshness-sensitive local-runtime lookups.
• Vaccine brand-name questions that miss on MyChem often need biomcp search drug <brand> --region eu, omitted --region, or explicit biomcp search drug <brand> --region who --product-type vaccine, which can bridge through CDC CVX/MVX into EMA or WHO vaccine matches.
• Review-literature questions: biomcp search article -k "<query>" --type review --limit 5
• Keyword-only article searches may return _meta.suggestions[] objects when the whole keyword exactly matches a gene, drug, or disease label/alias; use the suggested get gene, get drug, or get disease command when structured data may answer before more article paging.
• For repeated article keyword searches in one task, use JSON plus --session <token> with a short non-secret local label. If the next keyword overlaps the previous same-session keyword, _meta.suggestions[] can point to prior article batch, discover, or date narrowing instead of more reformulation.
• Some first-call JSON responses include _meta.workflow and _meta.ladder[]; these are static sidecar-backed multi-step ladders. Treat _meta.next_commands as dynamic one-hop follow-ups and _meta.ladder[] as the worked-example path for the named workflow.
• After search article, default to biomcp article batch <id1> <id2> ... instead of repeated get article calls. Batch up to 20 shortlisted papers in one call.
• Use biomcp batch gene <GENE1,GENE2,...> when you need the same basic card fields, chromosome, or sectioned output for multiple genes.
• For diseases with weak ontology-name coverage, run biomcp discover "<disease>" first, then pass a resolved MESH:..., OMIM:..., ICD10CM:..., MONDO:..., or DOID:... identifier to biomcp get disease.
• Multi-hop article follow-up: biomcp article citations <id> --limit 5 and biomcp article recommendations <id> --limit 5

Section reference

• get gene ... protein: UniProt function and localization detail
• get gene ... hpa: Human Protein Atlas tissue expression and localization
• get gene ... expression: GTEx tissue expression
• get gene ... diseases: disease associations
• get gene ... diagnostics: GTR diagnostic-test pivot for a gene
• get article ... annotations: PubTator normalized entity mentions for standardized extraction
• get article ... tldr: Semantic Scholar summary and influence
• get disease ... genes: associated genes
• get disease ... phenotypes: HPO phenotype annotations; source-backed and sometimes incomplete
• get disease ... pathways: pathways from associated genes
• get disease ... diagnostics: GTR and WHO IVD diagnostic-test pivot for a condition
• get diagnostic ... genes: joined gene names from the GTR detail bundle
• get diagnostic ... conditions: joined disease or condition names from GTR
• get diagnostic ... methods: source-native GTR testing methods
• get diagnostic ... regulatory: opt-in FDA device 510(k) and PMA overlay for supported diagnostic records
• get drug ... label: FDA label indications, warnings, and dosage
• get drug ... regulatory: regulatory summary
• get drug ... safety: safety context and warnings
• get drug ... interactions: DDInter-backed structured drug-drug interactions plus source-scoped empty wording
• get drug ... targets: ChEMBL and OpenTargets targets
• get drug ... indications: OpenTargets indication evidence

Cross-entity pivot rules

• gene articles <symbol> and search article -g <symbol> are equivalent starting points for gene-filtered literature.
• Use helpers when the pivot is obvious: drug interactions, drug trials, disease trials, variant articles, article citations.
• Use sectioned diagnostic pivots for gene or disease contexts: get gene <symbol> diagnostics and get disease <name_or_id> diagnostics. Use biomcp list diagnostic for source/filter/section details, and inspect returned IDs with get diagnostic <id> rather than inventing accessions or product codes.
• Use search article -d "<disease>" --type review --limit 5 when disease phenotypes or drug indications look sparse.
• Use article batch as the default multi-article follow-up after search article; it replaces sequential get article calls and preserves Semantic Scholar enrichment when available.
• Use batch <entity> <id1,id2,...> --sections <s1,s2,...> when you need the same card shape for several entities.
• Use enrich <GENE1,GENE2,...> once you have a real gene set and want pathways or GO-style categories.

How-to reference

For question patterns that need more than a one-line routing hint, start with the executable command or routing phrase below before you improvise the command sequence.

| Question pattern | Start with | Why | |---|---|---| | Specific variant pathogenicity or clinical-evidence question | biomcp get variant "<variant>" | Use the bounded variant-pathogenicity workflow instead of mixing ad hoc variant, trial, and article commands | | Specific drug safety or adverse-event question | biomcp drug adverse-events <name> and biomcp get drug <name> safety | Start with the drug-safety workflow before widening to literature | | Drug interaction question for a known medication | biomcp drug interactions <name> or biomcp get drug <name> interactions | Start with the DDInter-backed helper when the anchor drug is known, then widen to safety or literature only for nuance | | Drug approval, licensing, or regulatory-date question | biomcp get drug <name> regulatory | Use the structured-first workflow