biomcp

BioMCP

One binary. One grammar. Evidence from the biomedical sources you already trust.

Data terms

BioMCP retrieves data from upstream biomedical sources. Those sources' terms govern how you use the data they return: some restrict commercial or clinical use. Check each source's terms and obtain any licence you need before relying on the data. See Source Licensing and Terms for the per-source breakdown.

What is BioMCP?

BioMCP is one CLI binary over a single command grammar that reaches 70 trusted biomedical sources directly (PubMed, ClinVar, ClinicalTrials.gov, OncoKB, Reactome, and more; ten further sources arrive inside another source's answer). It is also an MCP (Model Context Protocol) server, so the same tools are available to AI agents such as Claude Code, Codex, and Claude Desktop.

BioMCP cuts through the usual biomedical data maze: one query reaches the sources that normally live behind different APIs, identifiers, and search habits. Researchers, clinicians, and agents use the same command grammar to search, focus, and pivot without rebuilding the workflow for each source. You get compact, evidence-oriented results across live public data plus local study analytics.

Features

• Search the literature: search article fans out across PubTator3 and Europe PMC, deduplicates PMID/PMCID/DOI identifiers, and can add a Semantic Scholar leg when your filters support it.
• Pivot without rework: move from a gene, variant, drug, disease, pathway, protein, or article straight into the next built-in view instead of rebuilding filters by hand.
• Choose a playbook: biomcp skill list shows shipped worked examples so you can open the matching biomcp skill <slug> workflow.
• Analyze studies locally: study commands cover local query, cohort, survival, compare, and co-occurrence workflows with native terminal, SVG, and PNG charts for downloaded cBioPortal-style datasets.
• Follow the paper trail: article citations, article references, article recommendations, and article entities turn one known paper into a broader evidence map.
• Enrich and batch: use biomcp enrich for top-level g:Profiler enrichment and biomcp batch for up to 10 focused get calls in one command.

Quick start

First useful query in under 30 seconds:

uv tool install biomcp-cli
biomcp health --apis-only
biomcp skill list
biomcp list gene
biomcp search all --gene BRAF --disease melanoma  # unified cross-entity discovery
biomcp get gene BRAF pathways hpa

Watch the introduction

A project using BioMCP won St. Jude's KIDS BioHackathon in 2025. The talk that followed is a one-hour introduction to BioMCP, recorded October 24, 2025.

Watch on YouTube · Read the write-up · Full transcript

Installation

Binary install

curl -fsSL https://biomcp.org/install.sh | bash

PyPI tool install

uv tool install biomcp-cli
# or: pip install biomcp-cli

PyPI package warning: install biomcp-cli, not biomcp. The biomcp PyPI package is unrelated to this project.

MCP Registry ownership marker: mcp-name: io.github.genomoncology/biomcp.

This installs the biomcp binary in ~/.local/bin. If that directory is not already on PATH, the installer prints one command to add it; it never edits your shell startup files.

Homebrew

brew tap genomoncology/biomcp
brew install biomcp

The separate genomoncology/homebrew-biomcp tap repository must exist before these commands can work.

Docker

docker run --rm ghcr.io/genomoncology/biomcp --version
docker run --rm ghcr.io/genomoncology/biomcp list
docker run --rm -i ghcr.io/genomoncology/biomcp serve

Use the GHCR image for quick CLI checks or stdio MCP clients without a local install.

Claude Code plugin

Install the biomcp binary first, then add the hosted plugin marketplace and install the BioMCP plugin in Claude Code:

/plugin marketplace add genomoncology/biomcp
/plugin install biomcp@biomcp

The plugin wires Claude Code to the local stdio MCP server with biomcp serve. For guided BioMCP workflows, also install the skill assets below.

Codex MCP server

Install the biomcp binary first, then register the same stdio MCP server with Codex:

codex mcp add biomcp -- biomcp serve

Claude Desktop extension (.mcpb)

Install BioMCP from the Anthropic Directory in Claude Desktop when that path is available for your environment. For local/manual setups, use the JSON MCP config below.

Install skills

Install guided investigation workflows into your agent directory:

biomcp skill install ~/.claude --force

MCP clients

{
  "mcpServers": {
    "biomcp": {
      "command": "biomcp",
      "args": ["serve"]
    }
  }
}

Remote HTTP server

For shared or remote deployments:

biomcp serve-http --host 127.0.0.1 --port 8080

Remote clients connect to http://127.0.0.1:8080/mcp. Probe routes are GET /health, GET /readyz, and GET /.

Runnable demo:

uv run --script examples/streamable-http/streamable_http_client.py

See Remote HTTP Server for the newcomer guide.

From source

make install
"$HOME/.local/bin/biomcp" --version

For repo-local verification, run the standard gates directly: make lint, make test, and make spec. make test includes both Rust nextest and the Python/docs contract lane, while make release-gate adds the named full-feature proof and runs specs against the all-feature release binary. There is no supported make check command. Use make verify only for opt-in live public-upstream confidence; make release-live-smoke remains a compatibility alias.

Command grammar

search <entity> [filters]    → discovery
skill list                   → playbook catalog for how-to questions
discover <query>             → concept resolution before entity selection
get <entity> <id> [sections] → focused detail
<entity> <helper> <id>       → cross-entity pivots
enrich <GENE1,GENE2,...>     → gene-set enrichment
batch <entity> <id1,id2,...> → parallel gets
search all [slot filters]    → counts-first cross-entity orientation

Entities and sources

The tables below distinguish detail-card entities from search-only surfaces so agents do not synthesize unsupported get commands.

Gettable entities

Entity	Upstream providers used by BioMCP	Example
gene	MyGene.info, UniProt, Reactome, QuickGO, STRING, GTEx, Human Protein Atlas, DGIdb, ClinGen, NIH Reporter, DisGeNET, GTR-backed diagnostics pivot	biomcp get gene BRAF pathways hpa
variant	MyVariant.info, ClinVar, direct gnomAD v4 population data, CIViC, Cancer Genome Interpreter, OncoKB, cBioPortal, GWAS Catalog, AlphaGenome	biomcp get variant "BRAF V600E" clinvar
article	PubMed, PubTator3, Europe PMC, PMC OA, NCBI ID Converter, Semantic Scholar (optional auth; S2_API_KEY recommended)	biomcp search article -g BRAF --limit 5
author	Semantic Scholar, ORCID	biomcp get author semanticscholar:1716151
trial	ClinicalTrials.gov API v2, NCI CTS API	biomcp search trial -c melanoma -s recruiting
diagnostic	NCBI Genetic Testing Registry local bulk bundle + WHO IVD local CSV + optional OpenFDA device overlay	biomcp get diagnostic GTR000006692.3 regulatory
drug	MyChem.info, DDInter local bundle, EMA local batch, WHO Prequalification local exports, ChEMBL, OpenTargets, Drugs@FDA, OpenFDA labels/shortages/approvals/FAERS/MAUDE/recalls, CIViC	biomcp drug interactions warfarin
disease	MyDisease.info, Monarch Initiative, MONDO, OpenTargets, Reactome, CIViC, SEER Explorer, NIH Reporter, DisGeNET, GTR/WHO IVD diagnostics pivot	biomcp get disease "Lynch syndrome" genes
pathway	Reactome, KEGG, WikiPathways, g:Profiler, Enrichr-backed enrichment sections	biomcp get pathway hsa05200 genes
protein	UniProt, InterPro, STRING, ComplexPortal, PDB, AlphaFold	biomcp get protein P15056 complexes
adverse-event	OpenFDA FAERS/MAUDE/recalls plus CDC WONDER VAERS aggregate vaccine search	biomcp search adverse-event --drug pembrolizumab
pgx	CPIC, PharmGKB	biomcp get pgx CYP2D6 recommendations
cell-line	Cellosaurus with ChEMBL, PharmacoDB, DepMap, COSMIC, GDSC, and LINCS cross-references	biomcp get cell-line CVCL_0004 xrefs

Search-only entities

Entity	Upstream providers used by BioMCP	Example
gwas	GWAS Catalog	biomcp search gwas --trait "type 2 diabetes"
phenotype	Monarch Initiative (HPO semantic similarity plus direct-support checks)	biomcp search phenotype "HP:0001250"

Cross-entity helpers

Pivot between related entities without rebuilding filters.

See the cross-entity pivot guide for when to use a helper versus a fresh search.

biomcp variant trials "BRAF V600E" --limit 5
biomcp variant articles "BRAF V600E"
biomcp drug adverse-events pembrolizumab
biomcp drug trials pembrolizumab
biomcp disease trials melanoma
biomcp disease drugs melanoma
biomcp disease articles "Lynch syndrome"
biomcp gene trials BRAF
biomcp gene drugs BRAF
biomcp gene articles BRCA1
biomcp gene pathways BRAF
biomcp pathway drugs R-HSA-5673001
biomcp pathway drugs hsa05200
biomcp pathway articles R-HSA-5673001
biomcp pathway trials R-HSA-5673001
biomcp protein structures P15056
biomcp article entities 22663011
biomcp article citations 22663011 --limit 3
biomcp article references 22663011 --limit 3
biomcp article recommendations 22663011 --limit 3

Gene-set enrichment

biomcp enrich BRAF,KRAS,NRAS --limit 10

Top-level biomcp enrich uses g:Profiler. Gene enrichment sections inside other entity views still reference Enrichr where that is the backing source.

Sections and progressive disclosure

Every get command supports selectable sections for focused output:

biomcp get gene BRAF                    # summary card
biomcp get gene BRAF pathways           # add pathway section
biomcp get gene BRCA1 diagnostics       # diagnostic-test pivot from GTR
biomcp get gene BRAF hpa                # protein tissue expression + localization
biomcp get gene BRAF civic interactions # multiple sections
biomcp get gene BRAF all                # standard sections; diagnostics/funding stay opt-in

biomcp get variant "BRAF V600E" clinvar population conservation
biomcp get article 22663011 tldr
biomcp get drug pembrolizumab label targets civic approvals
biomcp get drug trastuzumab regulatory --region who
biomcp get disease "Lynch syndrome" genes phenotypes variants
biomcp get disease tuberculosis diagnostics
biomcp get diagnostic GTR000006692.3 regulatory
biomcp get trial NCT02576665 eligibility locations outcomes

In JSON mode, get responses expose _meta.next_commands for the next likely follow-ups and _meta.section_sources for section-level provenance. batch ... --json returns per-entity objects with the same metadata shape.

API keys

Most commands work without credentials. Optional keys improve rate limits or unlock optional enrichments: