BioMCP

Apache-2.0 Docker Pulls MCP Smithery

One command grammar. 50+ biomedical databases. Zero learning curve.

Genes, variants, drugs, trials, papers, pathways, phenotypes — all through a single MCP endpoint.

BioMCP is a production-grade Model Context Protocol server that unifies PubMed, ClinicalTrials.gov, ClinVar, gnomAD, OncoKB, Reactome, KEGG, UniProt, PharmGKB, CPIC, OpenFDA, CDC VAERS, Monarch Initiative, GWAS Catalog, DisGeNET, AlphaGenome, cBioPortal, and 40+ other biomedical sources behind one consistent read-only API.

---

Quickstart

# Option A: Pull from Docker Hub (recommended)
docker pull jackgucci/biomcp:latest
docker compose up -d

# Option B: Build from source
git clone https://github.com/gucci10248/JEFFREY.git && cd JEFFREY
cp .env.example .env
bash build.sh
docker compose up -d

# Test
curl http://localhost:8080/health   # → {"status":"ok"}

Your MCP server is live at http://localhost:8080/mcp.

---

MCP Client Setup

Claude Desktop

{
  "mcpServers": {
    "biomcp": {
      "type": "streamableHttp",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Hermes Agent

# ~/.hermes/config.yaml
mcp:
  servers:
    biomcp:
      type: streamableHttp
      url: http://localhost:8080/mcp
      enabled: true

Any SSE/Streamable HTTP Client

Endpoint: http://localhost:8080/mcp

---

Command Reference

Genes

Command	Example
get gene <symbol>	get gene BRAF
get gene <symbol> diagnostics	get gene BRCA1 diagnostics
get gene <symbol> funding	get gene TP53 funding
search gene --region <chr:start-end>	search gene --region 7:140413127-140624564
gene pathways <symbol>	gene pathways EGFR
gene trials <symbol>	gene trials KRAS
gene articles <symbol>	gene articles PTEN
gene drugs <symbol>	gene drugs ALK

Variants

Command	Example
get variant "<name>"	get variant "BRAF V600E"
search variant --gene <symbol> --impact high	search variant --gene CFTR --impact high
variant trials <id>	variant trials "BRAF V600E"
variant articles <id>	variant articles "EGFR L858R"

Drugs

Command	Example
search drug --indication "<disease>"	search drug --indication hypertension
get drug <name>	get drug metformin
get drug <name> safety	get drug ibuprofen safety
get drug <name> regulatory --region eu	get drug rivaroxaban regulatory --region eu
drug interactions <name>	drug interactions warfarin
drug adverse-events <name>	drug adverse-events aspirin
drug trials <name>	drug trials pembrolizumab

Diseases

Command	Example
get disease <name>	get disease melanoma
get disease <name> funding	get disease tuberculosis funding
get disease <name> diagnostics	get disease HIV diagnostics
get disease <name> survival	get disease "breast cancer" survival
get disease <name> phenotypes	get disease "Parkinson disease" phenotypes
disease drugs <name>	disease drugs diabetes
disease trials <name>	disease trials "acute myeloid leukemia"
disease articles <name>	disease articles atherosclerosis

Articles (PubMed, Europe PMC, LitSense2)

Command	Example
search article -k "<query>" --type review	search article -k "CRISPR base editing" --type review
search article --gene <symbol> -k "<query>"	search article --gene APOE -k "Alzheimer risk"
search article --drug <name>	search article --drug metformin
get article <pmid>	get article 23193287
article citations <pmid>	article citations 23193287
article recommendations <pmid>	article recommendations 23193287
article entities <pmid>	article entities 23193287

Clinical Trials

Command	Example
search trial -c "<condition>"	search trial -c "type 2 diabetes"
search trial --gene <symbol>	search trial --gene BRAF
search trial --has-results	search trial -c melanoma --has-results
get trial <nct_id>	get trial NCT04280705
get trial <nct_id> locations	get trial NCT04280705 locations --limit 20

Pathways & Enrichment

Command	Example
search pathway "<name>"	search pathway "MAPK signaling"
get pathway <id>	get pathway hsa04010
pathway drugs <id>	pathway drugs hsa04151
enrich <gene list>	enrich TP53,EGFR,BRAF,KRAS

Phenotypes

Command	Example
search phenotype "<symptoms>"	search phenotype "seizure, developmental delay"
search phenotype "HP:... HP:..."	search phenotype "HP:0001250 HP:0001263"

GWAS

Command	Example
search gwas -g <gene>	search gwas -g APOE
search gwas --trait "<text>"	search gwas --trait "body mass index"
get gwas <id>	get gwas GCST90018969

Cross-Entity Search

Command	Example
search all --gene <symbol> --disease <name>	search all --gene BRAF --disease melanoma
discover "<free text>"	discover "chest pain"
suggest "<question>"	suggest "What drugs treat melanoma?"

Protein & Structure

Command	Example
get protein <accession>	get protein P00519
protein structures <accession>	protein structures P00519

Pharmacogenomics

Command	Example
get pgx <gene>	get pgx CYP2D6
search pgx --drug <name>	search pgx --drug clopidogrel

Adverse Events

Command	Example
search adverse-event --drug <name>	search adverse-event --drug metformin
search adverse-event --vaccine <name>	search adverse-event --vaccine "COVID-19 mRNA"

Operations

Command	Example
health	Check API connectivity
version	Print server version
batch <entity> <id1,id2,...>	batch gene BRAF,EGFR,TP53 --sections funding

---

Data Sources

Source	Coverage
PubMed	36M+ biomedical citations
Europe PMC	Full-text, preprints, patents
ClinicalTrials.gov	500K+ registered trials
ClinVar	3M+ variant-disease annotations
gnomAD	Population allele frequencies
OncoKB	Cancer variant clinical actionability
OpenFDA	FDA drug/device adverse events
UniProt	Protein function & structure
KEGG	Metabolic & signaling pathways
Reactome	Curated pathway database
PharmGKB	Pharmacogenomics knowledge
CPIC	Clinical pharmacogenetics guidelines
Monarch Initiative	Cross-species phenotype ontology
GWAS Catalog	Genome-wide association studies
cBioPortal	Cancer genomics datasets
DDInter	Drug-drug interaction database
CDC VAERS	Vaccine adverse events
EMA	European Medicines Agency data
WHO Prequalification	Essential medicines quality
NCBI GTR	Genetic testing registry
AlphaGenome	Genomic variant predictions
DisGeNET	Gene-disease associations

---

Features

• Read-only by design — no mutations to external data sources, safe for production
• Single command grammar — one pattern for all entity types, no learning curve
• Resilient — multi-source fallback, degraded responses with transparent source status
• Non-root container — runs as unprivileged biomcp user
• Read-only root filesystem — docker compose enforces read_only: true
• Minimal attack surface — single static binary, zero runtime dependencies
• Zero telemetry — no outbound calls except to public biomedical APIs
• SHA256-verified binary — build.sh verifies checksum from GitHub Releases
• Auto-updating data caches — EMA, WHO, GTR feeds auto-refresh on stale detection

---

Health & Monitoring

curl http://localhost:8080/health    # → {"status":"ok"} — API connectivity
curl http://localhost:8080/readyz    # → 200 — ready to serve traffic
curl http://localhost:8080/          # → Welcome page (HTML)

---

Requirements

• Docker 24+ & Docker Compose v2
• ~200MB disk (image + data volumes)
• Outbound internet access to public biomedical APIs
• Optional: NCBI_API_KEY, S2_API_KEY, UNPAYWALL_EMAIL for higher rate limits

---

Contributing

See SECURITY.md for vulnerability reporting and CODEOWNERS for maintainer contacts.

---

License

Apache License 2.0 — see LICENSE.