Skip to content

Command Line Interface Reference

BioMCP provides a comprehensive command-line interface for biomedical data retrieval and analysis. This guide covers all available commands, options, and usage patterns.

Installation

# Using uv (recommended)
uv tool install biomcp

# Using pip
pip install biomcp-python

Global Options

These options work with all commands:

biomcp [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit
  --help     Show help message and exit

Commands Overview

Domain Commands Purpose
article search, get Search and retrieve biomedical literature
trial search, get Find and fetch clinical trial information
variant search, get, predict Analyze genetic variants and predict effects
gene get Retrieve gene information and annotations
drug get Look up drug/chemical information
disease get Get disease definitions and synonyms
organization search Search NCI organization database
intervention search Find interventions (drugs, devices, procedures)
biomarker search Search biomarkers used in trials
health check Monitor API status and system health

Article Commands

For practical examples and workflows, see How to Find Articles and cBioPortal Data.

article search

Search PubMed/PubTator3 for biomedical literature with automatic cBioPortal integration.

biomcp article search [OPTIONS]

Options:

  • --gene, -g TEXT: Gene symbol(s) to search for
  • --variant, -v TEXT: Genetic variant(s) to search for
  • --disease, -d TEXT: Disease/condition(s) to search for
  • --chemical, -c TEXT: Chemical/drug name(s) to search for
  • --keyword, -k TEXT: Keyword(s) to search for (supports OR with |)
  • --pmid TEXT: Specific PubMed ID(s) to retrieve
  • --limit INTEGER: Maximum results to return (default: 10)
  • --no-preprints: Exclude preprints from results
  • --no-cbioportal: Disable automatic cBioPortal integration
  • --format [json|markdown]: Output format (default: markdown)

Examples:

# Basic gene search with automatic cBioPortal data
biomcp article search --gene BRAF --disease melanoma

# Multiple filters
biomcp article search --gene EGFR --disease "lung cancer" --chemical erlotinib

# OR logic in keywords (find different variant notations)
biomcp article search --gene PTEN --keyword "R173|Arg173|p.R173"

# Exclude preprints
biomcp article search --gene TP53 --no-preprints --limit 20

# JSON output for programmatic use
biomcp article search --gene KRAS --format json > results.json

article get

Retrieve a specific article by PubMed ID or DOI.

biomcp article get IDENTIFIER

Arguments:

  • IDENTIFIER: PubMed ID (e.g., "38768446") or DOI (e.g., "10.1101/2024.01.20.23288905")

Examples:

# Get article by PubMed ID
biomcp article get 38768446

# Get preprint by DOI
biomcp article get "10.1101/2024.01.20.23288905"

Trial Commands

For practical examples and workflows, see How to Find Trials with NCI and BioThings.

Search ClinicalTrials.gov or NCI CTS API for clinical trials.

biomcp trial search [OPTIONS]

Basic Options:

  • --condition TEXT: Disease/condition to search
  • --intervention TEXT: Treatment/intervention to search
  • --term TEXT: General search terms
  • --nct-id TEXT: Specific NCT ID(s)
  • --limit INTEGER: Maximum results (default: 10)
  • --source [ctgov|nci]: Data source (default: ctgov)
  • --api-key TEXT: API key for NCI source

Study Characteristics:

  • --status TEXT: Trial status (RECRUITING, ACTIVE_NOT_RECRUITING, etc.)
  • --study-type TEXT: Type of study (INTERVENTIONAL, OBSERVATIONAL)
  • --phase TEXT: Trial phase (EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4)
  • --study-purpose TEXT: Primary purpose (TREATMENT, PREVENTION, etc.)
  • --age-group TEXT: Target age group (CHILD, ADULT, OLDER_ADULT)

Location Options:

  • --country TEXT: Country name
  • --state TEXT: State/province
  • --city TEXT: City name
  • --latitude FLOAT: Geographic latitude
  • --longitude FLOAT: Geographic longitude
  • --distance INTEGER: Search radius in miles

Advanced Filters:

  • --start-date TEXT: Trial start date (YYYY-MM-DD)
  • --end-date TEXT: Trial end date (YYYY-MM-DD)
  • --intervention-type TEXT: Type of intervention
  • --sponsor-type TEXT: Type of sponsor
  • --is-fda-regulated: FDA-regulated trials only
  • --expanded-access: Trials offering expanded access

Examples:

# Find recruiting melanoma trials
biomcp trial search --condition melanoma --status RECRUITING

# Search by location (requires coordinates)
biomcp trial search --condition "lung cancer" \
  --latitude 41.4993 --longitude -81.6944 --distance 50

# Use NCI source with advanced filters
biomcp trial search --condition melanoma --source nci \
  --required-mutations "BRAF V600E" --allow-brain-mets true \
  --api-key YOUR_KEY

# Multiple filters
biomcp trial search --condition "breast cancer" \
  --intervention "CDK4/6 inhibitor" --phase PHASE3 \
  --status RECRUITING --country "United States"

trial get

Retrieve detailed information about a specific clinical trial.

biomcp trial get NCT_ID [OPTIONS]

Arguments:

  • NCT_ID: Clinical trial identifier (e.g., NCT03006926)

Options:

  • --include TEXT: Specific sections to include (Protocol, Locations, References, Outcomes)
  • --source [ctgov|nci]: Data source (default: ctgov)
  • --api-key TEXT: API key for NCI source

Examples:

# Get basic trial information
biomcp trial get NCT03006926

# Get specific sections
biomcp trial get NCT03006926 --include Protocol --include Locations

# Use NCI source
biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY

Variant Commands

For practical examples and workflows, see:

Search MyVariant.info for genetic variant annotations.

biomcp variant search [OPTIONS]

Options:

  • --gene TEXT: Gene symbol
  • --hgvs TEXT: HGVS notation
  • --rsid TEXT: dbSNP rsID
  • --chromosome TEXT: Chromosome
  • --start INTEGER: Genomic start position
  • --end INTEGER: Genomic end position
  • --assembly [hg19|hg38]: Genome assembly (default: hg38)
  • --significance TEXT: Clinical significance
  • --min-frequency FLOAT: Minimum allele frequency
  • --max-frequency FLOAT: Maximum allele frequency
  • --min-cadd FLOAT: Minimum CADD score
  • --polyphen TEXT: PolyPhen prediction
  • --sift TEXT: SIFT prediction
  • --sources TEXT: Data sources to include
  • --limit INTEGER: Maximum results (default: 10)
  • --no-cbioportal: Disable cBioPortal integration

Note: When searching by gene, OncoKB clinical actionability data is automatically included for BRAF, ROS1, and TP53 (or all genes if ONCOKB_TOKEN is set).

Examples:

# Search pathogenic BRCA1 variants
biomcp variant search --gene BRCA1 --significance pathogenic

# Search by HGVS notation
biomcp variant search --hgvs "NM_007294.4:c.5266dupC"

# Filter by frequency and prediction scores
biomcp variant search --gene TP53 --max-frequency 0.01 \
  --min-cadd 20 --polyphen possibly_damaging

# Search genomic region
biomcp variant search --chromosome 7 --start 140753336 --end 140753337

# OncoKB integration (uses free demo server for BRAF, ROS1, TP53 automatically)
biomcp variant search --gene BRAF

variant get

Retrieve detailed information about a specific variant. The --include-external flag also retrieves clinical actionability data from OncoKB for variants in BRAF, ROS1, and TP53 (or all genes if ONCOKB_TOKEN is set).

biomcp variant get VARIANT_ID [OPTIONS]

Arguments:

  • VARIANT_ID: Variant identifier (HGVS, rsID, or genomic)

Options:

  • --include-external / --no-external: Include annotations from external sources (TCGA, 1000 Genomes, cBioPortal, OncoKB) (default: true)
  • --json, -j: Output in JSON format
  • --assembly TEXT: Genome assembly (hg19 or hg38, default: hg19)

Examples:

# Get variant by HGVS (defaults to hg19)
biomcp variant get "NM_007294.4:c.5266dupC"

# Get variant by rsID
biomcp variant get rs121913529

# Specify hg38 assembly
biomcp variant get rs113488022 --assembly hg38

# JSON output with hg38
biomcp variant get rs113488022 --json --assembly hg38

# Without external annotations
biomcp variant get rs113488022 --no-external

# Get variant by genomic coordinates
biomcp variant get "chr17:g.43082434G>A"

variant predict

Predict variant effects using Google DeepMind's AlphaGenome (requires API key).

biomcp variant predict CHROMOSOME POSITION REFERENCE ALTERNATE [OPTIONS]

Arguments:

  • CHROMOSOME: Chromosome (e.g., chr7)
  • POSITION: Genomic position
  • REFERENCE: Reference allele
  • ALTERNATE: Alternate allele

Options:

  • --tissue TEXT: Tissue type(s) using UBERON ontology
  • --interval INTEGER: Analysis window size (default: 20000)
  • --api-key TEXT: AlphaGenome API key

Examples:

# Basic prediction (requires ALPHAGENOME_API_KEY env var)
biomcp variant predict chr7 140753336 A T

# Tissue-specific prediction
biomcp variant predict chr7 140753336 A T \
  --tissue UBERON:0002367  # breast tissue

# With per-request API key
biomcp variant predict chr7 140753336 A T --api-key YOUR_KEY

Gene/Drug/Disease Commands

For practical examples using BioThings integration, see How to Find Trials with NCI and BioThings.

gene get

Retrieve gene information from MyGene.info.

biomcp gene get GENE_NAME

Examples:

# Get gene information
biomcp gene get TP53
biomcp gene get BRAF

drug get

Retrieve drug/chemical information from MyChem.info.

biomcp drug get DRUG_NAME

Examples:

# Get drug information
biomcp drug get imatinib
biomcp drug get pembrolizumab

disease get

Retrieve disease information from MyDisease.info.

biomcp disease get DISEASE_NAME

Examples:

# Get disease information
biomcp disease get melanoma
biomcp disease get "non-small cell lung cancer"

NCI-Specific Commands

These commands require an NCI API key. For setup instructions and usage examples, see:

Search NCI's organization database.

biomcp organization search [OPTIONS]

Options:

  • --name TEXT: Organization name
  • --city TEXT: City location
  • --state TEXT: State/province
  • --country TEXT: Country
  • --org-type TEXT: Organization type
  • --api-key TEXT: NCI API key

Example:

biomcp organization search --name "MD Anderson" \
  --city Houston --state TX --api-key YOUR_KEY

Search NCI's intervention database.

biomcp intervention search [OPTIONS]

Options:

  • --name TEXT: Intervention name
  • --intervention-type TEXT: Type (Drug, Device, Procedure, etc.)
  • --api-key TEXT: NCI API key

Example:

biomcp intervention search --name pembrolizumab \
  --intervention-type Drug --api-key YOUR_KEY

Search biomarkers used in clinical trials.

biomcp biomarker search [OPTIONS]

Options:

  • --gene TEXT: Gene symbol
  • --biomarker-type TEXT: Type of biomarker
  • --api-key TEXT: NCI API key

Example:

biomcp biomarker search --gene EGFR \
  --biomarker-type mutation --api-key YOUR_KEY

Health Command

For monitoring API status before bulk operations, see the Performance Optimizations Guide.

health check

Monitor API endpoints and system health.

biomcp health check [OPTIONS]

Options:

  • --apis-only: Check only API endpoints
  • --system-only: Check only system resources
  • --verbose, -v: Show detailed information

Examples:

# Full health check
biomcp health check

# Check APIs only
biomcp health check --apis-only

# Detailed system check
biomcp health check --system-only --verbose

Output Formats

Most commands support both human-readable markdown and machine-readable JSON output:

# Default markdown output
biomcp article search --gene BRAF

# JSON for programmatic use
biomcp article search --gene BRAF --format json

# Save to file
biomcp trial search --condition melanoma --format json > trials.json

Environment Variables

Configure default behavior with environment variables:

# API Keys
export NCI_API_KEY="your-nci-key"
export ALPHAGENOME_API_KEY="your-alphagenome-key"
export CBIO_TOKEN="your-cbioportal-token"
export ONCOKB_TOKEN="your-oncokb-token"

# Logging
export BIOMCP_LOG_LEVEL="DEBUG"
export BIOMCP_CACHE_DIR="/path/to/cache"

Getting Help

Every command has a built-in help flag:

# General help
biomcp --help

# Command-specific help
biomcp article search --help
biomcp trial get --help
biomcp variant predict --help

Tips and Best Practices

  1. Use Official Gene Symbols: Always use HGNC-approved gene symbols (e.g., "TP53" not "p53")

  2. Combine Filters: Most commands support multiple filters for precise results:

biomcp article search --gene EGFR --disease "lung cancer" \
  --chemical erlotinib --keyword "resistance"
  1. Handle Large Results: Use --limit and --format json for processing:
biomcp article search --gene BRCA1 --limit 100 --format json | \
  jq '.results[] | {pmid: .pmid, title: .title}'
  1. Location Searches: Always provide both latitude and longitude:
# Find trials near Boston
biomcp trial search --condition cancer \
  --latitude 42.3601 --longitude -71.0589 --distance 25
  1. Use OR Logic: The pipe character enables flexible searches:
# Find articles mentioning any form of a variant
biomcp article search --gene BRAF --keyword "V600E|p.V600E|c.1799T>A"
  1. Check API Health: Before bulk operations, verify API status: 
    biomcp health check --apis-only

Next Steps