BioMCP
Highlights
Democratizing agentic access to bioinformatics and biopharmaceutical databases and analyses.
- Section-based federated access to 50+ bioinformatics, pharmaceutical, and patent databases
- Optional toolboxes for local database curation and dependency-free analysis with Bioconductor and SAM/BED/BCFtools — no R installation, C toolchain, or containers
- Concrete example vignettes, developed fully in the open
Install
npx -y biomcp doctor # diagnose a machine: Node gate, config health, feature gates, peer deps
npx biomcp # zero-config stdio MCP server (this is what MCP clients run); Node >= 22.13
Setup is guided in docs/AGENT-INSTALL.md — a one-minute start, copy-paste config entries for Claude Desktop, Claude Code, Codex, and OpenCode (one canonical pinned command covering every feature), biomcp doctor as the single troubleshooting entry point, and agent-friendly paths for API keys and optional features.
Available Tools
Full tool schemas (params, enums, defaults) live in src/server/README.md.
Gene (7)
| Tool | Description |
|---|
gene_search | Search genes by symbol, name, or keyword with chromosome filter |
gene_get | Get detailed gene info by HGNC symbol with optional sections (core, pathways, protein, ontology, go, interactions, expression, protein_atlas, constraint, druggability, dosage_sensitivity, clinical_evidence, disease_associations, diseases, funding). Set smart=true to auto-resolve gene aliases (e.g., "HER2" → "ERBB2") |
gene_diseases | Get diseases associated with a gene (DisGeNET / OpenTargets) |
gene_drugs | Find drugs targeting a gene (OpenTargets) |
gene_trials | Find clinical trials for a gene |
gene_articles | Find articles about a gene |
gene_enrich | Pathway enrichment analysis for a gene list (Reactome) |
Variant (4)
| Tool | Description |
|---|
variant_search | Search variants by rsid, HGVS, gene, ClinVar significance, frequency, CADD |
variant_get | Get detailed variant info with optional sections (frequency, predictions, clinical; alphagenome_scores currently returns an unavailability error pending reimplementation) |
variant_oncokb | Get OncoKB cancer variant annotations (requires ONCOKB_TOKEN) |
variant_trials | Find clinical trials for a variant |
Drug (3)
| Tool | Description |
|---|
drug_search | Search drugs by name, mechanism, or keyword |
drug_get | Get detailed drug info with optional sections (us_regulatory, eu_regulatory, who_regulatory, safety, targets, indications, adverse_events — FDA FAERS reactions ranked by report count) |
drug_trials | Find clinical trials for a drug |
Disease (4)
| Tool | Description |
|---|
disease_search | Search diseases by name, phenotype, or keyword |
disease_get | Get detailed disease info by ID (DOID, MONDO, OMIM, etc.) with optional sections (gene_associations, phenotypes, pathways) |
disease_drugs | Get drugs for a disease (OpenTargets) |
disease_trials | Get clinical trials for a disease (ClinicalTrials.gov) |
Article (2)
| Tool | Description |
|---|
article_search | Federated literature search across PubMed, EuropePMC, Semantic Scholar, PubTator, and LitSense with optional date range filtering |
article_get | Get detailed article info by identifier (PMID, PMCID, or DOI) with optional sections: oa (open access / license info), annotations, graph (citation graph), citation (fast/full citation data) |
Trial (2)
| Tool | Description |
|---|
trial_search | Search clinical trials by condition, intervention, status, or phase. Cursor-based pagination via page_token |
trial_get | Get detailed trial info by NCT ID with optional sections (eligibility, locations, outcomes) |
Utility (2)
| Tool | Description |
|---|
discover | Free-text concept resolution across all entity types |
batch_get | Retrieve multiple entities in parallel |
Structural Biology (1)
| Tool | Description |
|---|
pdb | Search PDB structures, get entry metadata with optional sections (polymer entities, ligands, assembly, experiment, citation), and download structure files (mmCIF/PDB) |
Patents (2)
| Tool | Description |
|---|
patent_search | Search patents worldwide (US, EP, WO, JP, 100+ authorities) with assignee/inventor/CPC/status/date filters and relevance ranking (sort_by). Quote exact multi-word concepts (e.g. "mRNA display"). Foundational prior art is auto-discovered via co-citation mining (seminal_prior_art; disable with seminal: false). Default backends: USPTO Public Search full-text (US, keyless, relevance-ranked) + EPO OPS (worldwide, keyed); uspto_odp (US bibliographic metadata) and google_patents (best-effort) available via source |
patent_get | Get patent details by publication number with sections: abstract, claims (US fulltext via USPTO Public Search; EP/WO via EPO OPS), citations (forward + backward), family, classifications |
GEO (2)
| Tool | Description |
|---|
geo_search | Search NCBI GEO for functional genomics studies (expression microarrays, RNA-seq, single-cell series) by entry type (GSE/GSM/GPL/GDS) and organism; results carry cross-links (sra_project, bioproject, pubmed_ids) for chaining |
geo_get | Get the full SOFT record for a GEO series/sample/platform: summary, organisms, sample preview (≤20), supplementary file URLs, and cross-references; optionally download the first supplementary file |
SRA (2)
| Tool | Description |
|---|
sra_search | Search NCBI's Sequence Read Archive for sequencing experiments and runs by free text, accession, or field syntax; returns experiment/study/sample accessions with library strategy and run counts |
sra_get | Get full details for an SRA accession: SRR run (instrument, spots, bases, size), SRX experiment (library design), SRP study (experiment list), or SRS sample; ENA/DDBJ accessions rejected with an ENA pointer |
GenBank (3)
| Tool | Description |
|---|
genbank_search | Search NCBI nucleotide records (GenBank/RefSeq/INSDC) by plain terms, accession, or field syntax; results include accession.version, definition, length, organism, topology |
genbank_get | Fetch a GenBank/RefSeq record as GenBank flat file or FASTA; whole records capped at 2 Mb — larger records require a seq_start/seq_stop region (up to 10 Mb, reverse-strand via strand=2) |
genbank_genes | Map a GenBank/RefSeq accession to its NCBI Gene IDs (elink nuccore→gene) for bridging into gene tools |
GTEx (2)
| Tool | Description |
|---|
gtex_expression | Get median gene expression across GTEx tissues (Analysis v10, 54 tissue sites, TPM, highest first); accepts HGNC symbol or Ensembl gene ID, with optional single-tissue filter |
gtex_eqtl | Get significant cis-eQTL associations for a gene in a specific GTEx tissue (v10): variant_id, p_value, NES, slope, sorted by ascending p-value |
Ensembl (4)
| Tool | Description |
|---|
ensembl_lookup | Resolve a gene in Ensembl terms for any of ~356 species: stable ID (+version), symbol, coordinates on the current assembly, canonical transcript; expand=true adds transcripts with translation/protein IDs |
ensembl_homology | Find orthologues/paralogues across species via Ensembl Compara — target stable IDs, taxonomy level, percent identity, sorted by identity; filter with target_species/target_taxon |
ensembl_consequence | Compute variant consequences on demand via Ensembl VEP for NOVEL variants and non-human species: most severe consequence, per-transcript effects (SIFT/PolyPhen), co-located ClinVar/COSMIC/gnomAD data. Known human variants get deeper pre-computed scores via variant_get; prefer HGVS input over rsIDs for precision |
ensembl_region | Query genes/transcripts/known variants in a genomic interval (chr:start-end) on the current assembly — locus triage |
R Analysis (4, optional — ANALYSIS_R=1)
| Tool | Description |
|---|
analysis_r_deseq2 | Differential expression for RNA-seq counts with Bioconductor DESeq2 (negative binomial, independent filtering, optional LFC shrinkage) in sandboxed WebAssembly R. Inputs: integer count matrix + sample metadata + design formula; output: markdown table of top genes by adjusted p-value with summary (format="json", include_full=true for full base64(gzip(TSV)) table) |
analysis_r_edger | Differential expression with edgeR — TMM normalization, empirical-Bayes dispersion, quasi-likelihood F-test (test="qlm") or 2-group exact test; same input/output contract |
analysis_r_limma | Differential expression with limma-voom — precision-weighted linear models with empirical-Bayes moderation; same input/output contract |
analysis_r_session_info | R runtime report: R/webR versions, installed package versions, memory, mirror endpoint — for diagnosing analysis issues |
First use starts a ~1 GB WebAssembly R worker and downloads the wasm package bundle (~62 MB) from GitHub releases (cached). Requires webr installed next to biomcp. Guide: docs/R-ANALYSIS.md.
Biowasm Analysis (8, optional — ANALYSIS_BIOWASM=1)
| Tool | Description |
|---|
analysis_bam_summary | Inspect an alignment (SAM/BAM/CRAM): header contigs, sample/read groups, flagstat mapping metrics, per-contig counts via idxstats when indexed — "what's in this BAM?" before region work |
analysis_bam_view_region | Reads, depth, pileup, or read extraction in a genomic region (samtools view/depth/mpileup); indexed sources use fast positional retrieval, indexless sources stream a BED filter (depth requires coordinate-sorted input and detects order violations), returning counts, coverage tables, SAM rows, or a BAM artifact |
analysis_bcf_summary | Inspect a VCF/BCF: contigs, sample count and names, INFO/FORMAT field inventory from the header |
analysis_bcf_view_region | Variants in a region as a narrow field projection (bcftools query): chosen columns, sample subsets, expression filters, variant types — or a sliced VCF.gz artifact |
analysis_bed_op | Interval algebra on BED tracks (bedtools intersect/merge/subtract/coverage/jaccard/sort) with the streaming -sorted algorithm for sorted inputs |
analysis_biowasm_convert | Format plumbing: SAM/BAM/CRAM via samtools view, VCF/BCF via bcftools view, VCF/BCF → TSV via bcftools query; results are artifact handles reusable as artifact_id |
analysis_biowasm_session_info | Biowasm runtime report: pinned tool versions, asset cache state, engine status, retained artifacts, memory |
analysis_biowasm_cli | Constrained escape hatch: an allowlisted samtools/bedtools/bcftools subcommand with schema-validated args (no shell, paths under /shared only) |
First use downloads checksum-verified wasm assets (~4.5 MB, cached); no extra npm packages. Indexed sources answer region queries with fast positional retrieval (~0.2 % of file read); indexless sources fall back to streaming BED filters. Guide: docs/BIOWASM-ANALYSIS.md.
Citation Module
Citations federate 5 providers in fast (~4s) or full (~15-30s) mode. Forward citation lists come from Europe PMC, OpenCitations, and Semantic Scholar; Crossref supplies counts and backward references. Provider matrix and schema details: src/server/README.md.
Optional Features
Capabilities that ship with the package but stay inactive until enabled. Each links to its own guide:
| Feature | Enable | Guide |
|---|
Database access — read-only SQL tools (db_query, db_list_tables, db_describe_table) for MySQL and local-file SQLite | Set DB_TYPE (+ connection env vars); MySQL needs the mysql2 peer dep — use the pinned one-shot client command (see docs/DATABASE.md) | docs/DATABASE.md |
R analysis — Bioconductor differential expression (analysis_r_deseq2, analysis_r_edger, analysis_r_limma, analysis_r_session_info) running DESeq2/edgeR/limma in sandboxed WebAssembly R; wasm packages download from GitHub releases at first use (~62 MB, cached; slow links: asset_timeout_ms or a self-fetched mirror_url) | Set ANALYSIS_R=1; needs the webr peer dep — use the pinned one-shot client command ["npx","-y","-p","biomcp@1.1","-p","webr@0.6","biomcp"] (all-features variant adds -p mysql2@3); expect ~1 GB RSS | docs/R-ANALYSIS.md |
| Biowasm analysis — samtools/bedtools/bcftools (BAM/BED/VCF) in sandboxed WebAssembly; streams/indexes real human-scale datasets (~300 MB BAM scans, region queries touch ~0.2 % of the file); assets ~4.5 MB cached at first use; no extra npm packages | Set ANALYSIS_BIOWASM=1 | docs/BIOWASM-ANALYSIS.md |
Instead of hand-editing env blocks, agents (and users) can self-serve through the always-available biomcp_configure tool: it reports every parameter's status/provenance, writes the .biomcp.json project config file for the optional features above (env vars keep precedence; env-only parameters are query-only and value-masked), validates changes, detects conflicts, checks peer-dependency prerequisites, and spells out the restart/verify steps. Details: docs/ENV-VARS.md → Project config file.
Documentation
License
Licensed under the Apache License, Version 2.0. See NOTICE for attributions.
BioMCP-TS is adapted from the upstream BioMCP Rust project (MIT) with an agent-first development approach and enhancements — kudos to the original authors.