BioMCP (Typescript) MCP Server

BioMCP

A high-performance MCP server that gives LLMs access to 25 biomedical tools federated across 50+ upstream APIs — genes, variants, drugs, diseases, literature, clinical trials, and structural biology in a single integration.

Adapted from the BioMCP Rust with agent-first development approach and enhancements. Kudos to the original authors.

Highlights

• 25 tools across 8 domains — search, retrieve, and cross-reference biomedical entities
• 50+ upstream sources — MyGene, MyVariant, MyChem, MyDisease, ClinVar, gnomAD, UniProt, Reactome, OpenTargets, CIViC, OncoKB, DisGeNET, GTEx, STRING, DGIdb, ClinicalTrials.gov, PubMed, EuropePMC, Semantic Scholar, PubTator, LitSense, Monarch Initiative, OpenFDA, NIH Reporter, AlphaGenome, and more
• Section-based fetching — entityGet(id, sections) fans out to multiple sources with per-section timeouts and graceful degradation (failed sections return { _error } instead of crashing)
• Federated article search — queries 5 literature backends simultaneously with PMID/PMCID/DOI deduplication
• Zero-config startup — works out of the box; optional API keys unlock higher rate limits and premium data
• 350+ unit tests (mocked) + 90+ integration tests (live APIs via in-process MCP client, with automatic retry on 429 rate limits)

Quick Start

Install and build

git clone <repo-url> && cd biomcp-ts
make install build

Configure with Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

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

Or from a local checkout:

{
  "mcpServers": {
    "biomcp": {
      "command": "node",
      "args": ["/path/to/biomcp-ts/dist/bundle.js"]
    }
  }
}

Direct stdio

npm start

Any MCP-compatible client

BioMCP speaks standard MCP over stdio. Point any MCP client at the biomcp binary or node dist/bundle.js.

Available Tools

Gene (7)

Tool	Description
gene_search	Search genes by symbol, name, or keyword with type/chromosome filters
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)
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)
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, survival)
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. Accepts query, source, limit, offset, and dateRange parameters.
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-mode or full citation data with citation_mode and citation_direction options)

Trial (2)

Tool	Description
trial_search	Search clinical trials by condition, intervention, status, or phase. Uses cursor-based pagination via page_token parameter
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)

Citation Module

Modes:

• Fast (default): Europe PMC, Semantic Scholar, Crossref (~4s)
  • Returns: Citations with title, authors, journal, year when available
  • Note: Crossref requires DOI; Europe PMC auto-resolves DOI/PMCID to PMID
• Full (citation_mode="full"): All 5 providers (~15-30s)
  • Adds: PubMed (PMID only) and OpenCitations (DOI only)
  • Use for: Comprehensive citation analysis

Provider Data Coverage:

Provider	Forward	Backward	Count	Required ID
Europe PMC	✓	✓	✓	PMID/DOI/PMCID
Semantic Scholar	✓	✓	✓	PMID/DOI/PMCID
Crossref	✓	✓	✓	DOI only
PubMed	✓	✓	✓	PMID only
OpenCitations	✓	✓	✓	DOI only

Automatic Fallback: Fast mode automatically queries PubMed when other providers return counts but no items (requires PMID).

Development

make              # Show available targets
make install      # Install dependencies
make build        # Compile and bundle into dist/bundle.js
make typecheck    # Type-check without emitting
make test         # Run unit tests (fast, mocked)
make test-integration  # Run integration tests (live APIs, ~60s)
make test-all     # Run all tests
make clean        # Remove build artifacts

Local Testing with npx

After building, you can test the MCP server locally via npx:

make build        # Creates dist/bundle.js
npx .             # Runs the bundled MCP server

This is the recommended workflow for local development and testing.

Environment Variables

All keys are optional. BioMCP works without any keys — they unlock higher rate limits and additional data sources.

Variable	Source	Benefit
NCBI_API_KEY	NCBI	Higher PubMed / NCBI rate limits
S2_API_KEY	Semantic Scholar API key (prevents 429 rate limits)
OPENFDA_API_KEY	OpenFDA	OpenFDA API access
NCI_API_KEY	NCI CTS	NCI Clinical Trials API
ONCOKB_TOKEN	OncoKB	OncoKB cancer variant annotations
DISGENET_API_KEY	DisGeNET	Disease-gene associations
UMLS_API_KEY	UMLS	UMLS terminology services
ALPHAGENOME_API_KEY	AlphaGenome	AlphaGenome variant scores

License

MIT