genomoncology/biomcp

BioMCP – a unified command‑line interface for biomedical evidence

What it is – BioMCP is a single‑binary CLI (and an MCP Model‑Context‑Protocol server) that lets you query ~30 trusted biomedical data sources—PubMed, ClinVar, ClinicalTrials.gov, OncoKB, Reactome, and many more—through a tiny, consistent command grammar. The same binary can be run locally, in a Docker container, or exposed as an HTTP/MCP server for AI‑assistant tools such as Claude Code, Codex, or Claude Desktop.

Why it matters – Researchers and clinicians normally have to stitch together dozens of APIs, each with its own identifiers and query syntax. BioMCP collapses that complexity: one search, get, or pivot command reaches the appropriate upstream service, de‑duplicates results, and returns a compact, provenance‑rich JSON or human‑readable table. The tool also ships skills—ready‑made, step‑by‑step workflows—that AI agents can invoke automatically.

Core capabilities

Capability	How you use it	Example
Unified literature search	`search article` (or `search all`) fans out to PubTator3, Europe PMC, PubMed and optionally Semantic Scholar, then deduplicates PMIDs/DOIs.	`biomcp search article -g BRAF --limit 5`
Cross‑entity pivoting	Jump from a gene → variant → drug → trial without rewriting filters.	`biomcp gene drugs BRAF`
Guided “skills”	A catalog of pre‑written investigation pipelines (e.g., “variant‑oncokb”, “disease‑trials”).	`biomcp skill list` → `biomcp skill variant-oncokb`
Local study analytics	Download cBioPortal‑style datasets and run cohort, survival, or co‑occurrence analyses, with SVG/PNG charts generated in‑terminal.	`biomcp study download msk_impact_2017`
Gene‑set enrichment	One‑liner wrapper around g:Profiler (or Enrichr for section‑level enrichment).	`biomcp enrich BRAF,KRAS,NRAS --limit 10`
Batch & streaming	Up to 10 `get` calls in a single command; HTTP streaming server for many concurrent workers.	`biomcp batch gene BRAF,KRAS,NRAS --json`
AI‑agent integration	Exposes an MCP server (`biomcp serve` or `serve‑http`) that Claude Code, Codex, or Claude Desktop can call as a tool.	`codex mcp add biomcp -- biomcp serve`

Installation paths (pick one)

Binary script – curl -fsSL https://biomcp.org/install.sh | bash
Python‑tool via uv/pip – uv tool install biomcp-cli (installs the biomcp binary in ~/.local/bin)
Homebrew – brew tap genomoncology/biomcp && brew install biomcp
Docker – docker run --rm ghcr.io/genomoncology/biomcp <command>
From source – make install (runs Rust nextest tests and Python docs contract checks)

Typical workflow (CLI)

# Quick sanity check
biomcp health --apis-only

# Discover everything about BRAF in melanoma
biomcp search all --gene BRAF --disease melanoma --counts-only

# Drill down to pathways and protein expression
biomcp get gene BRAF pathways hpa

# Pull variant evidence from ClinVar and gnomAD
biomcp get variant "BRAF V600E" clinvar population

# Enrich the gene set
biomcp enrich BRAF,KRAS,NRAS

The same sequence can be expressed as MCP calls from an LLM‑powered assistant, letting the model focus on reasoning while BioMCP supplies the factual evidence.

Who should use it

Biomedical researchers needing rapid, reproducible evidence tables across many databases.
Clinicians who want to pull variant, drug, or trial information without juggling separate web portals.
AI‑assistant developers looking for a deterministic, provenance‑rich tool that can be called from Claude, Codex, or other LLM agents.
Data analysts who want to download public study datasets (cBioPortal style) and run quick cohort visualisations from the terminal.

Limitations & gotchas

Most commands work without API keys, but higher rate limits or certain data (e.g., Semantic Scholar TL‑DR, OpenFDA, OncoKB) require you to set the appropriate environment variable.
Licensing of upstream sources is respected – BioMCP does not redistribute data, and some providers (KEGG, COSMIC) are only available in a read‑only, indirect fashion.
The HTTP MCP server shares a single process‑local rate‑limit; for heavy parallel workloads you should run one shared serve‑http endpoint behind a TLS‑terminating proxy.
The biomcp PyPI package is not the official CLI – install biomcp-cli instead.

Community & support

Issues & feature requests – https://github.com/genomoncology/biomcp/issues
Full docs – https://biomcp.org/
Demo video – St. Jude’s 2025 BioHackathon talk (YouTube link in README).
Citation – Use the provided CITATION.cff when the tool is used in publications.

TL;DR

BioMCP is a single‑binary, cross‑source biomedical query engine that speaks a tiny, consistent CLI grammar and an MCP server interface. It lets humans and LLM agents fetch literature, variants, drugs, trials, pathways, and more from dozens of trusted databases, pivot between entities without rewriting queries, and even run local study analytics—all without having to learn each upstream API.