biomcp-ts
BioMCP (Typescript)
Documentation
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
| Doc | Contents |
|---|---|
| docs/AGENT-INSTALL.md | Guided installation & client configuration (Claude Desktop, Claude Code, Codex, OpenCode) |
| docs/ENV-VARS.md | Single source of truth for every environment variable |
| docs/DATABASE.md | Database access feature guide |
| docs/R-ANALYSIS.md | R analysis feature guide (Bioconductor in WebAssembly) |
| docs/BIOWASM-ANALYSIS.md | Biowasm analysis feature guide (samtools/bedtools/bcftools in WebAssembly) |
| docs/DEVELOPMENT.md | Build, test, publish workflow |
| docs/development/CI.md | CI pipeline, Dependabot automation, auto-merge safety model |
| src/server/README.md | Full tool schemas (params, enums, defaults) |
| agent-test/README.md | User-agent E2E tests for the analysis tools |
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.
Frequently asked questions
What is biomcp-ts?
biomcp-ts is BioMCP (Typescript)
How do I install biomcp-ts?
Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.
Is biomcp-ts open source?
Yes — it is hosted on GitHub at https://github.com/yeyuan98/biomcp-ts and has 2 stars.
Related MCP tools
serversModel Context Protocol Servers
UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra
n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you
Figma-Context-MCPMCP server to provide Figma layout information to AI coding agents like Cursor
inbox-zeroThe world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.
instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP