Skip to main content
Glama

BioMCP

npm version downloads/mo downloads YTD commits/30d software DOI

BioMCP-TS architecture

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

Related MCP server: PubMed Advanced MCP Server

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.

Multiple agents on one machine: biomcp enforces arXiv's Terms-of-Use rate limit (1 request / 3 s) per process. When running multiple biomcp MCP instances on one machine (e.g., one stdio instance per agent), rate limits are not coordinated across processes, and arXiv's TOU applies to all your machines in aggregate. For multi-agent single-machine deployments, run a single shared biomcp serve daemon (see docs/SELF-HOSTING.md) so all agents share one process and one global rate limiter.

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; envelope { results, warnings?, errors? } — OpenTargets failures and unresolved genes ride in errors[], never as inline rows)

gene_trials

Find clinical trials for a gene

gene_articles

Find articles about a gene (federated across PubMed, EuropePMC, Semantic Scholar, arXiv, PubTator, LitSense; envelope { results, warnings?, errors? } — per-backend failures ride in errors)

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 (envelope { results, hint? } — when nothing matches, hint points mechanism/target queries at gene_drugs)

drug_get

Get detailed drug info with optional sections (us_regulatory, who_regulatory, safety, targets, indications, adverse_events — FDA FAERS reactions ranked by report count; WHO PQ listing lookup, ~650 global-health priority products)

drug_trials

Find clinical trials for a drug

Disease (4)

Tool

Description

disease_search

Search diseases by name, phenotype, or keyword (envelope { results, warnings?, errors? })

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; envelope { results, warnings?, errors? } — OpenTargets failures and unresolved diseases ride in errors[], never as inline rows)

disease_trials

Get clinical trials for a disease (ClinicalTrials.gov; envelope { results, warnings?, errors? })

Article (4)

Tool

Description

article_search

Federated literature search across PubMed, EuropePMC, Semantic Scholar, arXiv, PubTator, and LitSense with optional date range filtering; source: "preprint_only" switches to bioRxiv+medRxiv preprints only (abstracts, citation counts, date filtering). Result records carry journal_issn

article_get

Get detailed article info by identifier (PMID, PMCID, DOI, or bioRxiv/medRxiv preprint DOI) with optional sections: fulltext (the complete article text when freely readable in PMC/Europe PMC — open-access AND free-to-read articles; by default (fulltext_output="file") written to a server-side markdown file with the reply carrying file_path + an outline of headings with line numbers and char counts for selective Read/Grep, keeping body text out of the agent context; fulltext_output="inline" returns capped text sections via fulltext_max_chars, default 40000), oa (open-access/license metadata and links: status open_access/free_to_read/paywalled/not_in_pmc/unknown, license, pmc/pdf/doi links), annotations, graph (citation graph), citation (fast/full citation data; Europe PMC citations for preprints). all excludes fulltext. Preprint records include all versions, license, category, funders, JATS full-text URL (link only — use preprint_fulltext for the text), and published-version mapping. The record carries journal_issn

preprint_fulltext

On-demand bioRxiv/medRxiv preprint full text (JATS XML parsed to sections), by preprint DOI with optional version (default: latest). Strictly on-demand (never during search), downloads are paced (≥3 s spacing), cached per (doi, version) — JATS per version is immutable — and license-aware (cc_by → cc by + CC URL on every reply; the per-article license governs reuse). www.biorxiv.org rate-limits aggressively: on a 429/Cloudflare verdict all downloads pause ≥60 s (Retry-After honored) and calls during the cooldown get an honest rate_limited envelope with retry_after_sec; cached copies keep serving instantly. output="file" (default) writes a server-side markdown file (file_path + outline); output="inline" returns capped sections (fulltext_max_chars). Corpus-scale: use the bioRxiv/medRxiv monthly S3 buckets (https://www.biorxiv.org/tdm)

journal_metrics

OpenAlex journal quality metrics (2yr mean citedness — an open-access impact-factor alternative), h-index, quality lists; by name, NLM abbreviation, or ISSN

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. "flow cytometry"). 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 when configured, otherwise Google Patents pages), 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 (bioproject, pubmed_ids; sra_project when NCBI links the SRA study — otherwise geo_get's sra field) 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. GDS curated DataSets return structured guidance ({ accession, guidance, see_also: { series, sample } }) pointing at the underlying GSE/GSM instead of a record

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: run (SRR/ERR/DRR — instrument, spots, bases, size), experiment (SRX/ERX/DRX — library design), study (SRP/ERP/DRP — experiment list), or sample (SRS/ERS/DRS); NCBI SRA indexes NCBI, ENA, and DDBJ accessions alike

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.6","-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.

Available Tools

43 tools
article_getA
Read-only

Get article by PMID/PMCID/DOI. Section response keys differ from request names: "oa" is stored as sections.open_access, "graph" as sections.citation_graph. Preprint DOIs (bioRxiv/medRxiv, e.g. "10.1101/2025.03.05.641768" or new prefix "10.64898/...") return the preprint record: all versions, license, category, funders, JATS full-text URL, published-version mapping, and (with sections=["citation"]) Europe PMC preprint citations. Journal articles, sections=["fulltext"]: returns the ACTUAL full text when freely readable in PMC/Europe PMC (open-access AND free-to-read). fulltext.status is "available" or "unavailable"; when unavailable, fulltext.reason is one of paywalled | no_pmcid | no_machine_readable_xml | not_implemented_for_preprints | fetch_failed (with alternatives in links, e.g. doi_url); a transiently failed OA-status lookup counts as no status info, so a paywalled in-PMC article surfaces as fetch_failed until a retry reclassifies it as paywalled. The five-value open-access vocabulary — open_access | free_to_read | paywalled | not_in_pmc | unknown — is sections.open_access.status (request sections:["oa"]); fulltext.oa_status echoes it so paywalled vs not-in-PMC is visible without the oa section. Default (fulltext_output="file"): the complete text is written to a server-side markdown file and the reply carries file_path plus an outline with per-section line numbers and char counts — Read/Grep the file selectively instead of loading it into context. fulltext_output="inline" (use only if you cannot read server-side files): fulltext.sections is an ordered array of {heading, text, truncated} objects plus char_count/total_char_count/truncated/omitted_sections, capped by fulltext_max_chars. sections=["oa"] returns license/access metadata and links ONLY (pdf_url presence does not by itself mean the text is fetchable — use fulltext for content). "all" = oa+annotations+graph+citation WITHOUT fulltext (request ["fulltext"] separately). oa/fulltext do not apply to preprints (see the jatsxml_url link). Journal-article citation: fast mode (~4s, 4 providers, auto-fallback to PubMed) or full mode (~15-30s, all 5 providers incl. PubMed). Forward citation lists come from Europe PMC, Semantic Scholar, and OpenCitations; Crossref provides counts and references only.

Inputs: id (required), limit, sections, citation_mode, +3 more.

article_searchA
Read-only

Search literature across multiple backends with federated search and deduplication. Response is an envelope: { results, warnings?, errors? } — per-source failures ride in errors (never as items inside results), degradation notes (e.g. PubMed dropping unrecognized query terms, LitSense relevance-floor drops) in warnings. LitSense rows carry the matched sentence plus PubMed-enriched title/metadata when available.

Inputs: query (required), limit, offset, source, +1 more.

batch_getA
Read-only

Get multiple entities in parallel. Article items return metadata (with inline abstract) by default; for full text pass sections:["fulltext"] on the item — PMC articles then return a small file handle (file_path + outline, never body text inline) while non-PMC articles return an explicit unavailable + reason. Nonexistent PMIDs yield a per-item error and the batch continues. For inline text use article_get with fulltext_output="inline"

Inputs: inputs (required).

biomcp_configureA
DestructiveIdempotent

Inspect and configure biomcp — unified observability and restricted controllability for every parameter.

What it covers: three optional feature groups (database, analysis_r, analysis_biowasm) whose knobs live in the .biomcp.json project config file (written by this tool, loaded at server startup — a restart applies changes), plus every environment-only parameter (API keys, proxy, security boundaries), which is query-only.

Actions:

  • status (default; call with {}): per-feature running state (with each feature's settable_keys), config file health, conflicts (e.g. an env var vetoing the file), pending-restart flags, dependency prerequisites, and parameter counts. The full parameter catalog is NOT inlined — use filter for detailed rows: 'file', 'env', a feature id ('analysis_r'), or a dotted-id prefix ('features.database').

  • set: create/modify file parameters in one atomic batch. Enable/disable is just features..enabled. null removes a key (restores default). Sensitive keys (connection targets, mirrors) require confirm_sensitive=true. Nothing is written when any key is invalid (dry_run=true validates and diffs without writing).

  • reset: remove a feature section (target: feature id) or specific keys (target: [dotted ids]).

Hard rules: environment parameters are never settable here (the response tells you how to set them in your client's env block); env var values are never displayed (masked: presence + fingerprint only); the file write is refused when the server's working directory is not a project root — the response then carries a paste-ready env block instead.

Examples: {"action":"status"} · {"action":"status","filter":"features.analysis_r"} · {"action":"set","values":{"features.analysis_biowasm.enabled":true}} · {"action":"set","values":{"features.database.enabled":true,"features.database.type":"sqlite","features.database.sqlite_path":["data/geo.db"]}} · {"action":"set","values":{"features.analysis_r.mirror_url":null}} · {"action":"reset","target":"analysis_r"}

Changes apply at server startup: finish dependency prerequisites first (see prerequisites in the response), then restart the client/session once, then re-call this tool with {} to verify running_now.

Inputs: action, filter, target, values, +2 more.

discoverA
Read-only

Free-text concept resolution - find entities matching a free-text query. Prefers a candidate whose name/symbol exactly matches the query (case-insensitive), ranks those exact matches first across entity types, and demotes numbered susceptibility-locus labels (e.g. "lung cancer susceptibility 1") within each backend's candidates; each result's matched_on field reports why it was picked ("exact" or "first")

Inputs: query (required).

disease_drugsA
Read-only

Get drugs for a disease via OpenTargets. Results are ranked by max clinical phase, then trial-report count, with salt forms collapsed. Response is an envelope: { results, warnings?, errors? } — OpenTargets failures and unresolved diseases ride in errors[] as { source, message, retryable? } instead of inline items (issue #130)

Inputs: disease_id (required), limit.

disease_getC
Read-only

Get detailed disease information by ID

Inputs: disease_id (required), limit, sections.

disease_trialsB
Read-only

Get clinical trials for a disease. Response is an envelope: { results, warnings?, errors? } (issue #130)

Inputs: disease_id (required), limit.

drug_getC
Read-only

Get detailed drug information by name

Inputs: name (required), limit, sections.

drug_trialsB
Read-only

Find clinical trials for a drug

Inputs: drug (required).

ensembl_consequenceA
Read-only

Predict the functional consequence of a variant on demand via Ensembl VEP — works even for NOVEL variants absent from every database, and for non-human species.

Input forms: HGVS c./p./g. notation ("NM_004333:c.1799T>A", "NM_004333.6:c.1799T>A") or a dbSNP rsID ("rs113488060"). Prefer HGVS over rsIDs when both are available — rsIDs are resolved through dbSNP's coordinate mapping, which can yield less specific consequences. RefSeq accessions may carry a version ("NM_004333.6:c.1799T>A"); when the version is not carried by the current Ensembl release the call is retried against the bare accession and the result flags the reinterpretation in warnings. Per-species rules: the variant must be valid on a transcript of THAT species — RefSeq NM_ accessions work cross-species only when the transcript belongs to it (e.g. "NM_011640:c.100A>G" + species 'mouse' is mouse Trp53; a human NM_ fed to species 'mouse' fails). Ensembl transcript IDs (ENST…, ENSMUST…) are accepted for their own species, and c./p. positions must be in range for the transcript. Invalid input returns the upstream VEP error explaining what could not be mapped. Returns the most severe consequence plus per-transcript effects (impact, codon/amino-acid change, SIFT/PolyPhen where available) and co-located known variants (ClinVar/COSMIC IDs, gnomAD/1000G frequencies when present). For KNOWN human variants, variant_get additionally provides deep pre-computed scores (CADD, REVEL, AlphaMissense, ClinVar stars) — prefer it there.

Inputs: variant (required), limit, species.

ensembl_homologyA
Read-only

Find orthologues or paralogues of a gene across species (Ensembl Compara) — the cross-species gene mapping source in biomcp.

Returns target stable IDs, gene symbols (when the assembly provides them, e.g. ARAF/RAF1 for BRAF paralogs), species, taxonomy level, and percent identity, sorted by identity. Accepts an HGNC symbol or Ensembl gene ID; scope to one species with target_species ('mouse') or target_taxon (10090). Use it for conservation questions ('is this gene conserved?', 'what is the mouse orthologue of BRAF?').

Inputs: gene (required), type, limit, species, +2 more.

ensembl_lookupA
Read-only

Resolve a gene in Ensembl terms for ANY Ensembl species (356 available): stable ID (ENSG…), symbol↔ID mapping, versioned identifier, canonical transcript, and coordinates on the current assembly (GRCh38 human, GRCm39 mouse, …). With expand=true, returns all transcripts with translation/protein IDs.

Accepts an HGNC symbol (BRAF) or Ensembl gene ID (ENSG00000157764, versioned or bare — versions are resolved to the current record). Species accepts scientific names or aliases ('homo_sapiens'/'human', 'mus_musculus'/'mouse'). For rich human gene annotation (summary, pathways, drugs, diseases) use gene_get instead — this tool is the identifier/structure authority.

Inputs: gene_or_id (required), expand, species.

ensembl_regionA
Read-only

Query what lives in a genomic interval on the current assembly (GRCh38 for human): genes/transcripts (stable IDs, symbols, biotypes) and known variants (rsIDs, alleles, consequence terms, clinical significance).

Ideal for locus triage — "what genes and known variants sit in this GWAS hit interval?". Genes/transcripts are always fetched for the FULL requested span, but variation density can reach ~100k variants in dense loci (which times out upstream), so when the span exceeds 50 kb variation is queried only for a 50 kb window centered on the region midpoint — the result echoes effective_variation_window (the coordinates actually queried for variation) and variation_truncated (names the dropped span) when this cap applies. To sweep variation across a large interval, issue adjacent region calls. Keep spans modest (<1 Mb recommended); output is capped at limit with a truncated marker. For sequence text use genbank_get; for entity-level annotation chain IDs into gene_get / variant_get.

Inputs: region (required), limit, species, features.

genbank_genesA
Read-only

Map a GenBank/RefSeq nucleotide accession to its NCBI Gene IDs (elink nuccore→gene).

The returned gene_ids are NCBI Gene (entrezgene) IDs. gene_get takes an HGNC gene symbol, NOT a numeric entrez id, so an id must first be resolved to its symbol — gene_search result rows carry both symbol and entrez_id, so the id→symbol bridge exists via gene_search. Useful bridge from a sequence record to gene-level annotation.

Inputs: accession (required).

genbank_getA
Read-only

Fetch a GenBank/RefSeq nucleotide record as text (GenBank flat file or FASTA).

Whole-record fetches are capped at 2,000,000 bp — larger records require a seq_start/seq_stop region (1-based, inclusive, up to 10 Mb span; set strand=2 for a reverse-strand slice where seq_start > seq_stop — the region field echoes the request as given, while NCBI's text shows complement(min..max)). Output: records up to 1,000 characters are returned inline (sequence_text with char_count/truncated). Anything larger defaults to file mode — the FULL text is written to a server-side cache file and the reply carries mode:"file", file_path, char_count, and total_char_count instead of sequence_text (never truncated); Read/Grep the file selectively. The cache is ephemeral (pruned after ~7 days / 500 files) and the path is server-local; re-call to regenerate. sequence_output:"inline" opts back into inline text capped at 200,000 characters — use it only if you cannot read server-side files.

Inputs: accession (required), format, strand, seq_stop, +3 more.

gene_articlesA
Read-only

Find articles about a gene. Response is an envelope: { results, warnings?, errors? } — per-backend failures ride in errors (never as items inside results), degradation notes in warnings (issue #130)

Inputs: symbol (required).

gene_diseasesA
Read-only

Get diseases associated with a gene. Requires DISGENET_API_KEY environment variable for DisGeNET data; falls back to OpenTargets gene-disease associations when unavailable.

Inputs: symbol (required), limit.

gene_drugsA
Read-only

Find drugs targeting a gene. Results are ranked by max clinical phase, then trial-report count, with salt forms collapsed. Response is an envelope: { results, warnings?, errors? } — OpenTargets failures and unresolved genes ride in errors[] as { source, message, retryable? } instead of inline items (issues #130, #179)

Inputs: symbol (required).

gene_enrichA
Read-only

Perform pathway enrichment analysis for a gene list (Reactome over-representation). Requires at least 3 genes; the list is deduplicated (case-insensitive) before submission. Each pathway reports genes_overlap — the count of unique SUBMITTED genes Reactome matched there, resolved with one follow-up token lookup (Reactome's entity-level match count can exceed the gene count when one gene maps to multiple entities, e.g. a UniProt entry plus Ensembl gene/transcript). The reply also reports how many pathways Reactome found in total alongside the returned page. Typical completion is 15–45 s (the Reactome analysis takes 8–22 s per step across two sequential steps), with a worst case around 105 s including one retry per step; requires reachability of reactome.org, and clients whose request timeout is 60 s may need to raise it for large result follow-ups.

Inputs: genes (required), limit.

gene_getA
Read-only

Get detailed gene information by symbol. Response section keys mirror the requested section names: sections:["clinical_evidence"] returns sections.clinical_evidence, "protein_atlas" returns sections.protein_atlas, "dosage_sensitivity" returns sections.dosage_sensitivity, "disease_associations" returns sections.disease_associations — the legacy storage keys (civic, hpa, clingen, disgenet) never appear in responses.

Inputs: symbol (required), limit, smart, sections.

gene_trialsA
Read-only

Find clinical trials for a gene

Inputs: symbol (required).

geo_getA

Get the full SOFT record details for a GEO entry: series (GSE...), sample (GSM...), or platform (GPL...).

A series detail includes summary, organisms, platform_ids, a sample preview, supplementary file URLs, and cross-references for chaining: sra → sra_get(SRP.../SRR...), pubmed_ids → article_get, samples → geo_get(GSM...), platform_ids → geo_get(GPL...).

GDS accessions (curated DataSets, not served by SOFT) return structured guidance as data — { accession, guidance, see_also: { series: "GSE…", sample: "GSM…" } } — pointing at the underlying series/sample records; this is a successful result, not an error. Malformed accessions still fail at schema validation.

download=true additionally saves a supplementary file to a local temp path and returns its path, size, and source URL — the pick prefers .gz/.csv/.txt, else the first listed supplementary file (subject to max_bytes).

Inputs: accession (required), download, max_bytes.

gtex_eqtlA
Read-only

Get significant cis-eQTL associations for a gene in a specific GTEx tissue (GTEx Analysis v10): variant_id, p_value, and NES (effect direction/size), sorted by ascending p-value.

tissue is a required GTEx tissueSiteDetailId (e.g. Whole_Blood, Brain_Cortex).

An empty associations list is a VALID scientific result — the gene was tested but has no significant cis-eQTLs in that tissue (not a lookup failure). In that case the result carries a note listing other tissues where significant eQTLs DO exist (or stating that none exist in any tissue).

Inputs: gene (required), tissue (required), limit.

gtex_expressionA
Read-only

Get median gene expression across GTEx tissues (GTEx Analysis v10, 54 tissue sites, TPM, sorted highest first).

Accepts an HGNC symbol (TP53) or Ensembl gene ID (ENSG00000141510, versioned or bare). Optionally filter to a single tissue via its tissueSiteDetailId (e.g. Brain_Cortex, Whole_Blood).

Inputs: gene (required), limit, tissue.

journal_metricsA
Read-only

Journal quality metrics — an open-access alternative to the Clarivate impact factor (IF). Returns the OpenAlex 2-year mean citedness score (an IF-style metric), h-index, i10-index, citation counts, open-access flag (is_oa), and quality-list tiers (e.g. medline, norway-2, jufo-3…). Accepts a journal name, NLM abbreviation (e.g. 'N Engl J Med'), or ISSN (e.g. '0028-0836'; article records carry journal_issn).

Inputs: query (required), limit.

patent_getA
Read-only

Get patent details by publication number (e.g. "US11027025B2", "EP3904939B1", "US20260240819A1"). Sections: abstract, claims (US fulltext via USPTO Public Search; EP/WO via EPO OPS when configured, otherwise Google Patents pages — see per-section source fields), citations (backward + forward), family, classifications. US claims may fall back to an unofficial Google Patents rendering when PPUBS is slow or unreachable — flagged in _warnings. Section failures are reported per section (inline error entry plus a _warnings note), never by failing the whole call.

Inputs: patent_id (required), limit, sections.

pdbA

Access the Protein Data Bank (RCSB PDB) for macromolecular structure data.

SEARCH: Provide "query" to find structures (e.g., "kinase inhibitor", "hemoglobin"). GET: Provide "pdb_id" to retrieve entry metadata with optional detail sections. Sections list per-entity records (polymer_entities, ligands, assembly); when some records fail while siblings succeed, each failure appears as an inline {_error} item AND the response carries a top-level "warnings" array naming the section and failed item. DOWNLOAD: Provide "pdb_id" + download=true to save the structure file and get the file path.

Inputs: limit, query, format, offset, +3 more.

preprint_fulltextA
Read-only

On-demand bioRxiv/medRxiv preprint full text (JATS XML, parsed to sections). Input: a preprint DOI (e.g. "10.1101/2025.03.05.641768"), optional version (default: latest). Downloads are strictly on-demand (never run during search), paced, and cached per (doi, version) — JATS per version is immutable, so repeat calls are served from cache without re-downloading. www.biorxiv.org rate-limits aggressively: on a 429/Cloudflare verdict this tool pauses downloads for >=60s (Retry-After honored) and every call during the cooldown returns an honest unavailable/rate_limited envelope with retry_after_sec — cached copies are still served instantly. The per-article license (cc by, cc by-nc-nd, na, ...) rides on every reply and governs reuse; for corpus-scale text mining use the bioRxiv/medRxiv monthly S3 buckets (see https://www.biorxiv.org/tdm). Output "file" (default): complete text written to a server-side markdown file, reply carries file_path + outline (Read/Grep selectively); "inline": capped text sections (fulltext_max_chars, default 40000).

Inputs: id (required), output, version, fulltext_max_chars.

sra_getA
Read-only

Get full details for an SRA accession indexed by NCBI: run (SRR/ERR/DRR — instrument, spots, bases, size), experiment (SRX/ERX/DRX — library design), study (SRP/ERP/DRP — experiment list), or sample (SRS/ERS/DRS). NCBI SRA indexes NCBI, European (ENA), and DDBJ submissions alike, so accessions returned by sra_search resolve here regardless of prefix.

Chain from geo_get (sra field) or sra_search (experiment_accession / first_run_accession).

Inputs: accession (required).

trial_getC
Read-only

Get detailed trial information by NCT ID

Inputs: nct_id (required), limit, sections.

variant_getA
Read-only

Get detailed variant information with optional sections. Core data (id, gene, rsid, significance) is always returned at the top level. Use sections to request additional data. Response section keys mirror the requested section names: sections:["alphagenome_scores"] returns sections.alphagenome_scores — the legacy storage key (alphagenome) never appears in responses.

Inputs: id (required), limit, sections.

variant_oncokbB
Read-only

Get OncoKB annotations for a variant in a cancer gene. Requires ONCOKB_TOKEN environment variable.

Inputs: gene (required), protein_change (required).

variant_trialsA
Read-only

Find clinical trials for a variant. Response is an envelope: { results, warnings? } — when MyVariant.info ID resolution fails, a warning rides alongside the results (which then come from searching the raw identifier) so a backend failure never masquerades as "no trials exist"; retry may resolve BRAF V600E-style naming (issue #198)

Inputs: variant (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 43 tools

    Disambiguation4/5

    Most tools follow a clear entity+action split (gene_/variant_/drug_/disease_/article_/trial_/geo_/sra_/genbank_/patent_ + search/get), and descriptions actively steer agents apart (e.g. drug_search explicitly says it is not a target search, use gene_drugs; gene_get vs ensembl_lookup is carved out). A few overlaps remain that will cause misselection: five routes into clinical trials (drug_trials, gene_trials, variant_trials, disease_trials, trial_search), preprint_fulltext versus article_get on a preprint DOI, and discover versus the per-entity *_search tools. Batch_get also shadows every get tool.

    Naming Consistency4/5

    The dominant convention is consistent snake_case entity_verb (gene_search/gene_get, variant_trials, article_get, geo_search, patent_get), which makes the set predictable. Deviations exist: pdb is a bare noun doing search/get/download in one tool, discover and batch_get are generic verbs without an entity, and journal_metrics/gene_enrich are noun_verb or verb-only rather than entity_action.

    Tool Count3/5

    43 tools is heavy, but the breadth is genuine (genes, variants, drugs, diseases, trials, literature, patents, PDB, GEO/SRA/GenBank, GTEx, Ensembl, config), and most domains are well-scoped search/get pairs that earn their place. Still, several convenience wrappers (gene_articles, gene_diseases, gene_drugs, gene_trials, batch_get) could be folded into generic search tools, so the surface feels larger than strictly necessary.

    Completeness4/5

    Coverage of the bioinformatics domain is broad and lifecycle-complete for most entities: search+get for genes, variants, drugs, diseases, trials, articles, patents, sequences, structures, with rich cross-linking hints (sra→sra_get, geo→sra, genbank_genes→gene_search). Minor gaps: Reactome enrichment is the only pathway tool and has no reverse lookup, there is no protein/UniProt target tool separate from PDB, and no batch/list-upload path except the generic batch_get and gene_enrich gene lists.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers