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, search	Retrieve gene information and annotations
disease	get, search	Get disease definitions and synonyms
drug	get, search	Retrieve drug information from MyChem.info
organization	search	Search NCI organization database
intervention	search	Find interventions (drugs, devices, procedures)
biomarker	search	Search biomarkers used in trials
openfda	various	Search FDA data (adverse events, drug labels)
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.

trial search

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:

• Get Comprehensive Variant Annotations
• Predict Variant Effects with AlphaGenome

variant search

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/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 with optional functional enrichment analysis.

biomcp gene get GENE_NAME [OPTIONS]

Options:

• --enrich TEXT: Enrichment analysis type (feature in development)
• --json, -j: Output in JSON format

Available enrichment types (feature in development):

• pathway, kegg, reactome, wikipathways
• ontology, go_process, go_molecular, go_cellular
• celltypes, tissues
• diseases, gwas
• transcription_factors, tf
• --enrich, -e TEXT: Add functional enrichment analysis (pathway, ontology, celltypes, etc.)
• --json, -j: Output in JSON format

Available Enrichment Types:

Category	Short Name	Full Database Name
Pathways	pathway	KEGG_2021_Human
	kegg	KEGG_2021_Human
	reactome	Reactome_2022
	wikipathways	WikiPathways_2024_Human
Gene Ontology	ontology	GO_Biological_Process_2021
	go_process	GO_Biological_Process_2021
	go_molecular	GO_Molecular_Function_2021
	go_cellular	GO_Cellular_Component_2021
Cell Types	celltypes	PanglaoDB_Augmented_2021
	tissues	Human_Gene_Atlas
Diseases	diseases	DisGeNET
	gwas	GWAS_Catalog_2023
TFs	transcription_factors	ChEA_2022
	tf	ChEA_2022

Examples:

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

# Gene information with enrichment (feature in development)
biomcp gene get TP53 --enrich pathway
biomcp gene get BRCA1 --enrich ontology
biomcp gene get EGFR --enrich celltypes

# JSON output
biomcp gene get TP53 --json

gene search

Basic gene information

biomcp gene get TP53 biomcp gene get BRAF

With pathway enrichment

biomcp gene get TP53 --enrich pathway

With Gene Ontology enrichment

biomcp gene get BRCA1 --enrich ontology

With cell type associations

biomcp gene get EGFR --enrich celltypes

Using full database name

biomcp gene get TP53 --enrich KEGG_2021_Human

JSON output with enrichment

biomcp gene get TP53 --enrich pathway --json

**Note:** Enrichment analysis is powered by the Enrichr API and inspired by [gget enrichr](https://github.com/pachterlab/gget) (Luebbert & Pachter, 2023).

### drug get

Search for genes in MyGene.info database.

```bash
biomcp gene search QUERY [OPTIONS]

Options:

• --page, -p INTEGER: Page number (default: 1)
• --page-size INTEGER: Results per page (default: 10, max: 100)
• --json, -j: Output in JSON format

Examples:

# Search by gene symbol
biomcp gene search TP53

# Search by gene name
biomcp gene search "tumor protein"

# Search with pagination
biomcp gene search kinase --page 2 --page-size 20

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"
biomcp disease get GIST

disease search

Search for diseases in MyDisease.info or NCI CTS database.

biomcp disease search [NAME] [OPTIONS]

Options:

• --source TEXT: Data source: 'mydisease' (default) or 'nci'
• --category TEXT: Disease category/type filter (NCI only)
• --page INTEGER: Page number (default: 1)
• --page-size INTEGER: Results per page (default: 20, max: 100)
• --api-key TEXT: NCI API key (required for NCI source)

Examples:

# Search MyDisease.info (default)
biomcp disease search melanoma

# Search NCI cancer terms
biomcp disease search melanoma --source nci

# Filter by category
biomcp disease search --category neoplasm --source nci

Drug Commands

Retrieve comprehensive drug information from MyChem.info, which aggregates data from multiple sources including DrugBank, ChEMBL, PubChem, and more.

drug get

Retrieve detailed drug information by name or identifier.

biomcp drug get DRUG_ID_OR_NAME [OPTIONS]

Arguments:

• DRUG_ID_OR_NAME: Drug name, trade name, or identifier (DrugBank ID, ChEMBL ID, PubChem CID)

Options:

• --json, -j: Output in JSON format

Examples:

# Get drug information by name
biomcp drug get imatinib
biomcp drug get aspirin

# Get drug by identifier
biomcp drug get DB00945  # DrugBank ID
biomcp drug get CHEMBL25  # ChEMBL ID

# JSON output for programmatic use
biomcp drug get imatinib --json

Output includes:

• Drug identifiers (DrugBank, ChEMBL, PubChem, ChEBI, UNII)
• Description and mechanism of action
• Trade names and synonyms
• Chemical properties
• Links to external databases

drug search

Search for drugs in the MyChem.info database.

biomcp drug search QUERY [OPTIONS]

Arguments:

• QUERY: Drug name, trade name, or search term

Options:

• --page, -p INTEGER: Page number (default: 1)
• --page-size INTEGER: Results per page (default: 10, max: 100)
• --json, -j: Output in JSON format

Examples:

# Search by drug name
biomcp drug search imatinib

# Search by partial name
biomcp drug search "kinase inhibitor"

# Search with pagination
biomcp drug search aspirin --page 2 --page-size 20

# JSON output
biomcp drug search imatinib --json

Note: Full search with pagination is currently in development. The search currently returns basic drug information for the query term.

NCI-Specific Commands

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

• Authentication and API Keys
• How to Find Trials with NCI and BioThings

organization search

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

intervention search

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

biomarker search

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

• Set up API keys for enhanced features
• Explore MCP tools for AI integration
• Read how-to guides for complex workflows