Skip to content

Quickstart: BioMCP CLI

Get started with BioMCP in under 5 minutes! This guide walks you through installation and your first biomedical search.

Prerequisites

  • Python 3.10 or higher
  • uv package manager (recommended) or pip

Installation

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install BioMCP
uv tool install biomcp-python

Option 2: Using pip

pip install biomcp-python

Let's search for recent articles about BRAF mutations in melanoma:

biomcp article search \
  --gene BRAF --disease melanoma

This command:

  • Searches PubMed/PubTator3 for articles
  • Filters by BRAF gene and melanoma disease
  • Returns the 5 most recent results
  • Automatically includes cBioPortal cancer genomics data
  • Includes preprints from bioRxiv/medRxiv by default

Understanding the Output

The search returns:

  1. cBioPortal Summary (if gene specified): Cancer genomics data showing mutation frequencies and hotspots
  2. Article Results: Each result includes:
  3. Title and authors
  4. Journal and publication date
  5. PubMed ID and direct link
  6. Abstract snippet
  7. Annotated entities (genes, diseases, chemicals)

Essential Commands

Search Clinical Trials

Find active trials for lung cancer:

biomcp trial search \
  --condition "lung cancer" \
  --status open

Get Gene Information

Retrieve details about the TP53 tumor suppressor:

biomcp variant search --gene TP53 # get variants for a gene
biomcp article search --gene TP53 # find articles about a gene

Get gene information with functional enrichment analysis:

# Pathway enrichment (KEGG, Reactome, WikiPathways)
biomcp gene get TP53 --enrich pathway

# Gene Ontology enrichment
biomcp gene get BRCA1 --enrich ontology

# Cell type associations
biomcp gene get EGFR --enrich celltypes

# Available enrichment types:
# - pathway, kegg, reactome, wikipathways
# - ontology, go_process, go_molecular, go_cellular
# - celltypes, tissues
# - diseases, gwas
# - transcription_factors, tf

You can also search for genes:

biomcp gene search "tumor protein"

Get Disease Information

Get details about diseases from MyDisease.info:

biomcp disease get melanoma
biomcp disease get "lung cancer"

Get Drug Information

Get comprehensive drug information from MyChem.info:

biomcp drug get imatinib
biomcp drug get aspirin

You can also search by drug identifiers:

biomcp drug get DB00945  # DrugBank ID
biomcp drug get CHEMBL25  # ChEMBL ID
biomcp intervention search imatinib

Search for Genetic Variants

Find pathogenic variants in the BRCA1 gene:

biomcp variant search \
  --gene BRCA1 --significance pathogenic

Analyze a Clinically Actionable Variant

Get OncoKB clinical interpretations for known cancer variants. BioMCP uses a demo server for key genes like BRAF out-of-the-box, no setup required!

# Get clinical actionability for BRAF V600E
biomcp variant search --gene BRAF

This will automatically prepend an "OncoKB Gene Summary" table to the search results.

Next Steps

Some features require API keys for enhanced functionality:

# For NCI clinical trials database
export NCI_API_KEY="your-key-here"

# For AlphaGenome variant predictions
export ALPHAGENOME_API_KEY="your-key-here"

# For additional cBioPortal features
export CBIO_TOKEN="your-token-here"

See Authentication and API Keys for detailed setup.

Explore Advanced Features

  • Combine Multiple Filters:
biomcp article search \
  --gene EGFR --disease "lung cancer" \
  --chemical erlotinib
  • Use OR Logic in Keywords:
biomcp article search --gene BRAF --keyword "V600E|p.V600E|c.1799T>A"
  • Exclude Preprints: 
    biomcp article search --gene TP53 --no-preprints

Get Help

View all available commands:

biomcp --help

Get help for a specific command:

biomcp article search --help

Common Use Cases

1. Research a Specific Mutation

# Find articles about EGFR T790M resistance mutation
biomcp article search --gene EGFR \
  --keyword "T790M|p.T790M" \
  --disease "lung cancer"

2. Find Trials for a Patient

# Active trials for HER2-positive breast cancer
biomcp trial search \
  --condition "breast cancer" \
  --keyword "HER2 positive" \
  --status RECRUITING

3. Investigate Genes, Diseases, and Drugs

# Get gene information
biomcp gene get TP53

# Get disease information
biomcp disease get melanoma

# Get drug information
biomcp drug get imatinib

# Find articles about the gene in a specific disease
biomcp article search --gene TP53 --disease melanoma

Troubleshooting

Command Not Found

If biomcp is not recognized:

  • Ensure your PATH includes the installation directory
  • Try running with full path: ~/.local/bin/biomcp
  • Restart your terminal after installation

No Results Found

If searches return no results:

  • Check spelling of gene names (use official symbols)
  • Try broader search terms
  • Remove filters one by one to identify the constraint

API Rate Limits

If you encounter rate limit errors:

  • Add delays between requests
  • Consider setting up API keys for higher limits
  • Use the --limit parameter to reduce result count

Next Steps

Now that you've run your first searches, explore these resources:

  1. Complete CLI Reference - Comprehensive documentation for all commands and options
  2. Claude Desktop Integration - Use BioMCP with AI assistants
  3. Set up API Keys - Enable advanced features with NCI, AlphaGenome, and cBioPortal
  4. How-to Guides - Step-by-step tutorials for complex research workflows
  5. Deep Researcher Persona - Learn about BioMCP's philosophy and methodology

Happy researching! 🧬🔬