Heuris BioMCP

---

Live Demo

Try Heuris-BioMCP without installing — connect to our live server:

https://heuris-biomcp.onrender.com/mcp

If hosted auth is enabled, Claude-compatible clients will complete the OAuth redirect flow automatically. Non-interactive clients can also use bearer API keys.

Connect to Live Server

For Claude, use Customize > Connectors and enter:

https://heuris-biomcp.onrender.com/mcp

For generic remote MCP clients that accept URL-based server definitions:

{
  "mcpServers": {
    "heuris-biomcp": {
      "url": "https://heuris-biomcp.onrender.com/mcp"
    }
  }
}

Note: https://heuris-biomcp.onrender.com/mcp is the recommended remote MCP endpoint for modern clients. The legacy SSE endpoint remains available at https://heuris-biomcp.onrender.com/sse.

---

See Heuris-BioMCP in Action

Quick Demo Video

Watch how to connect Heuris-BioMCP to Claude Desktop:

Tip: Coming soon - video walkthrough of connecting Heuris-BioMCP and running your first query!

---

What is Heuris-BioMCP?

Heuris-BioMCP bridges MCP clients and high-value life-science data sources through a curated public tool surface. The server exposes the workflows that matter most for product review and research use, while lower-level helper modules remain internal for composition and planner logic.

You -> "What drugs target EGFR and what clinical trials are recruiting?"
ChatGPT + Heuris-BioMCP -> Queries ChEMBL + ClinicalTrials.gov -> Structured answer

---

What's New in v2.3

• Curated the public MCP surface from a broad 71-tool registry down to a strategy-driven set of 32 review-friendly tools
• Merged operational suites into workflow tools: find_protein, pathway_analysis, crispr_analysis, drug_safety, variant_analysis, and session
• Added new translational tools: drug_interaction_checker, protein_binding_pocket, biomarker_panel_design, pharmacogenomics_report, protein_family_analysis, network_enrichment, rnaseq_deconvolution, structural_similarity, rare_disease_diagnosis, and genome_browser_snapshot
• Removed low-signal or niche tools from the public MCP registry while keeping lower-level code available internally
• Preserved hosted HTTP/SSE deployment and operational endpoints for production-style MCP review
• Added optional hosted OAuth 2.1 PKCE and API-key auth for authenticated remote connectors
• Added Prometheus metrics, streamed progress chunks for slow tools, persistent gene/disease/watch MCP resources, and literature watch workflows

---

Tools (32 curated public surface)

Core Research

Tool	Description
search_pubmed	PubMed literature search with MeSH, Boolean syntax, abstracts, and metadata
get_gene_info	NCBI Gene summary with aliases, locus, and functional context
run_blast	NCBI BLAST sequence alignment
get_protein_info	Full UniProt Swiss-Prot protein record
find_protein	Unified UniProt plus PDB protein discovery workflow
get_alphafold_structure	AlphaFold structure metadata and confidence summary
pathway_analysis	Merged KEGG plus Reactome pathway workflow
get_drug_targets	ChEMBL drug-target evidence for a gene
get_gene_disease_associations	Open Targets translational gene-disease evidence
search_clinical_trials	ClinicalTrials.gov recruiting-trial search
multi_omics_gene_report	Integrated multi-database flagship gene report

AI And Engineering Workflows

Tool	Description
predict_structure_boltz2	Boltz-2 structure workflow with optional protein-ligand mode
generate_dna_evo2	Evo2 generation or WT-vs-variant scoring workflow
crispr_analysis	Merged CRISPR design, scoring, off-target, base-edit, and repair workflow
drug_safety	Merged FDA safety workflow for events, signals, labels, and comparisons
variant_analysis	Merged ACMG, gnomAD, ClinVar, splice, and integrated variant reporting
session	Merged entity, graph, export, and adaptive planning workflow

High-Value Translational Tools

Tool	Description
find_repurposing_candidates	Drug repurposing workflow over literature, trials, and target evidence
verify_biological_claim	Cross-database biological claim verification
search_cbio_mutations	Cancer mutation frequency search
search_gwas_catalog	GWAS trait-association search
drug_interaction_checker	FDA label-based interaction screening
protein_binding_pocket	Candidate binding-site summary from annotated protein features
biomarker_panel_design	Disease-focused biomarker panel drafting
pharmacogenomics_report	CPIC-style pharmacogenomics summary with PGx evidence
protein_family_analysis	Protein family and domain context
network_enrichment	Gene-set pathway and interaction-hub enrichment summary
rnaseq_deconvolution	Marker-based bulk RNA-seq deconvolution
structural_similarity	PubChem-based chemical structural similarity search
rare_disease_diagnosis	Phenotype normalization plus OMIM-oriented rare-disease differential support
genome_browser_snapshot	Browser-ready locus context for genes and genomic intervals

Public Surface Policy

• The MCP registry is intentionally curated.
• Lower-level legacy implementations still exist in the package for internal orchestration and testing.
• Reviewers should evaluate the exposed MCP surface, not the hidden implementation inventory.

---

Databases & AI Models

Source	Domain	URL
Traditional Databases
NCBI PubMed	Literature	https://pubmed.ncbi.nlm.nih.gov
NCBI Gene	Genomics	https://www.ncbi.nlm.nih.gov/gene
NCBI BLAST	Sequence Alignment	https://blast.ncbi.nlm.nih.gov
NCBI GEO	Gene Expression	https://www.ncbi.nlm.nih.gov/geo
UniProt Swiss-Prot	Proteomics	https://www.uniprot.org
AlphaFold DB	Protein Structure	https://alphafold.ebi.ac.uk
RCSB PDB	Protein Structure	https://www.rcsb.org
KEGG	Pathways	https://www.kegg.jp
Reactome	Pathways	https://reactome.org
ChEMBL	Drug Discovery	https://www.ebi.ac.uk/chembl
Open Targets	Gene-Disease	https://platform.opentargets.org
Ensembl	Genomics	https://www.ensembl.org
ClinicalTrials.gov	Clinical	https://clinicaltrials.gov
Human Cell Atlas	Single-Cell	https://data.humancellatlas.org
OpenNeuro	Neuroimaging	https://openneuro.org
NeuroVault	Neuroimaging	https://neurovault.org
v2 Extended Databases
OMIM	Genetic Diseases	https://www.omim.org
STRING	Protein Interactions	https://string-db.org
GTEx	Expression Atlas	https://gtexportal.org
cBioPortal	Cancer Genomics	https://www.cbioportal.org
GWAS Catalog	Trait Associations	https://www.ebi.ac.uk/gwas
DisGeNET	Disease-Gene	https://www.disgenet.org
PharmGKB	Pharmacogenomics	https://www.pharmgkb.org
v2.2 Tier 2 Databases
BioGRID	Protein Interactions	https://thebiogrid.org
Orphanet	Rare Diseases	https://www.orpha.net
GDC / TCGA	Tumor Genomics	https://portal.gdc.cancer.gov
CellMarker	Cell Type Markers	http://xteam.xbio.top/CellMarker
ENCODE	Regulatory Elements	https://www.encodeproject.org
MetaboLights	Metabolomics	https://www.ebi.ac.uk/metabolights
UCSC Genome Browser	Splice Isoforms	https://genome.ucsc.edu
Safety, Variant & Innovation Sources
OpenFDA / FAERS	Drug Safety	https://api.fda.gov
DailyMed	Drug Labels	https://dailymed.nlm.nih.gov
ClinVar	Clinical Variants	https://www.ncbi.nlm.nih.gov/clinvar
gnomAD	Population Variation	https://gnomad.broadinstitute.org
bioRxiv / medRxiv	Preprints	https://www.biorxiv.org
InterPro	Protein Domains	https://www.ebi.ac.uk/interpro
COSMIC	Cancer Mutations	https://cancer.sanger.ac.uk/cosmic
AI Models (NVIDIA NIM)
MIT Boltz-2	Structure Prediction	https://build.nvidia.com/mit/boltz2
Arc Evo2-40B	DNA Generation	https://build.nvidia.com/arc/evo2-40b

---

Quick Start

Option 1: Use Live Demo (No Installation)

Use Claude's Customize > Connectors flow and enter:

https://heuris-biomcp.onrender.com/mcp

If you are connecting with an older MCP client that still expects SSE, use:

https://heuris-biomcp.onrender.com/sse

Option 2: Deploy Your Own

Deploy to Render with one click:

Deploy to Render

Or manually:

1. Fork this repository
2. Create a new Web Service on Render
3. Connect your fork
4. Set build command: pip install -r requirements.txt && pip install -e .
5. Set start command: BIOMCP_TRANSPORT=http BIOMCP_HTTP_PORT=$PORT python -m biomcp

Hosted Deployment Limitations

• Session snapshots saved through the session tool are only durable if BIOMCP_SESSION_STORE_DIR points to persistent storage.
• On Render free tier, the default local directory uses ephemeral disk and will be wiped on restart, redeploy, or scale-to-zero wake-up.
• If you need persistent saved sessions, set BIOMCP_SESSION_STORE_DIR to a mounted persistent path or move session persistence behind an external store before relying on cross-session restore.

Hosted Auth and Connector Setup

• For Anthropic-style hosted connectors, enable BIOMCP_AUTH_ENABLED=1.
• OAuth 2.1 PKCE is exposed at /.well-known/oauth-authorization-server, /oauth/authorize, /oauth/token, and /oauth/register.
• For machine-to-machine clients, set BIOMCP_API_KEYS and send either Authorization: Bearer <key> or X-API-Key: <key>.
• Per-key limits are controlled with BIOMCP_API_KEY_RATE_LIMIT_REQUESTS and BIOMCP_API_KEY_RATE_LIMIT_WINDOW_SECONDS.

Persistent Resources and Literature Watches

• biomcp://gene/{SYMBOL} returns a curated gene context resource with gene, protein, pathway, disease, and drug-target context.
• biomcp://disease/{URL-ENCODED-NAME} returns disease literature plus session-graph context.
• session(action="watch") registers a PubMed + bioRxiv watch and exposes biomcp://watch/{TOPIC} as a reusable resource.
• Saved sessions and watches are only persistent if the backing session-store directory is durable.

Privacy, Support, and Data Handling

• Privacy policy: PRIVACY.md
• Support channel: SUPPORT.md
• Data handling notes: DATA_PROCESSING.md
• Security reporting: SECURITY.md

Option 3: Local Installation

Prerequisites

• Python 3.11+
• Claude Desktop or any MCP-compatible client
• (Optional) NCBI API key for higher rate limits
• (Optional) NVIDIA API keys for AI tools

Installation

# Clone the repository
git clone https://github.com/SachinGawande2003/Heuris-BioMCP.git
cd Heuris-BioMCP

# Install (standard)
pip install -e .

# Install with neuroimaging support
pip install -e ".[neuroimaging]"

# Install with dev dependencies (recommended)
pip install -e ".[dev]"

Configure Claude Desktop

For Local STDIO Mode (default):

{
  "mcpServers": {
    "heuris-biomcp": {
      "command": "biomcp",
      "env": {
        "NCBI_API_KEY": "your_ncbi_api_key_here"
      }
    }
  }
}

For Remote HTTP Mode (using live demo or your own deployed server):

Use Claude's Customize > Connectors flow and enter:

https://heuris-biomcp.onrender.com/mcp

If you are connecting with an older MCP client that still expects SSE, use:

https://heuris-biomcp.onrender.com/sse

💡 Tip: Get a free NCBI API key to increase rate limits from 3 to 10 requests/second.

🚀 New: Get free NVIDIA API keys for AI tools at build.nvidia.com/mit/boltz2 and build.nvidia.com/arc/evo2-40b.

Restart Claude Desktop and test:

"Search PubMed for recent papers on CAR-T cell therapy in B-cell lymphoma"
"Get the AlphaFold structure for TP53 and tell me about the confidence scores"
"What drugs are approved that target EGFR?"
"Generate a multi-omics report for KRAS"
"Predict the structure of EGFR with ligand CC1=CC=CC=C1 and compute binding affinity"
"Generate a DNA sequence starting with ATGGCG..."

---

Usage Examples

Literature Mining

"Search PubMed for BRCA1 CRISPR correction methods published in the last 2 years"
"Find review articles about PD-1/PD-L1 immune checkpoint inhibitors"

Protein Analysis

"Get UniProt info for human TP53 (P04637) including its domains and disease associations"
"Search for AlphaFold structures for insulin receptor"
"Find all PDB crystal structures of BRAF kinase domain resolved below 2.5 Ångström"

Drug Discovery

"What are the top ChEMBL compounds targeting KRAS G12C mutation?"
"Get compound info for imatinib (CHEMBL941)"
"Show me gene-disease associations for BRCA1 with evidence scores"

AI-Powered Structure Prediction

"Predict the 3D structure of insulin (sequence: ...) with ligand CCO"
"Compute binding affinity between EGFR and gefitinib (SMILES: ...)"
"Get structure prediction for a protein-protein complex"

AI-Powered DNA Generation

"Generate a 200bp promoter sequence starting with ATG"
"Compare wildtype vs variant DNA sequence for TP53 mutation"
"Generate regulatory element for gene expression"

Multi-Omics Report (Flagship)

"Generate a complete multi-omics report for EGFR"

This single command queries 7 databases in parallel and returns:

• Genomic location and gene summary (NCBI Gene)
• Recent publications (PubMed)
• Protein function and structure (UniProt + AlphaFold)
• Biological pathways (Reactome)
• Drug targets and clinical compounds (ChEMBL)
• Disease associations with scores (Open Targets)
• Expression datasets (GEO)
• Active clinical trials (ClinicalTrials.gov)

v2 Extended Databases

"Get OMIM diseases associated with TP53"
"Show STRING protein interactions for EGFR"
"Get GTEx expression data for BRCA1 across tissues"
"Find mutations in TP53 from cBioPortal"
"Search GWAS for diabetes-associated SNPs"

v2 Verification

"Verify the claim that TP53 is a tumor suppressor gene"
"Detect conflicts between OMIM and DisGeNET for BRCA1"

v2 Experimental Design

"Generate an experimental protocol for CRISPR knockout of BRCA1"
"What cell lines should I use to study KRAS mutations?"
"Calculate sample size for detecting 2-fold change with p<0.05"

v2 Session Intelligence

"What's the knowledge graph from our conversation so far?"
"Find biological connections between TP53 and EGFR"
"Export our research session as a reproducible script"
"Plan and execute a research workflow for PD-1 drug targets"

---

Architecture

biomcp/
├── src/biomcp/
│   ├── server.py              # MCP server — tool registry & dispatcher
│   ├── tools/
│   │   ├── ncbi.py            # PubMed, Gene, BLAST
│   │   ├── proteins.py        # UniProt, AlphaFold, PDB
│   │   ├── pathways.py        # KEGG, Reactome, ChEMBL, Open Targets
│   │   ├── advanced.py        # ClinicalTrials, GEO, scRNA, Ensembl,
│   │   │                      # Multi-Omics, Neuroimaging, Hypothesis
│   │   ├── nvidia_nim.py      # Boltz-2, Evo2-40B AI models
│   │   ├── databases.py       # v2: OMIM, STRING, GTEx, cBioPortal,
│   │   │                      #      GWAS, DisGeNET, PharmGKB
│   │   ├── verify.py          # v2: Claim verification, conflict detection
│   │   └── protocol_generator.py  # v2: Experimental design tools
│   ├── core/
│   │   ├── entity_resolver.py # v2: Cross-database entity resolution
│   │   ├── knowledge_graph.py # v2: Session knowledge graph
│   │   └── query_planner.py   # v2: Adaptive query planner
│   └── utils/
│       └── __init__.py        # Rate limiter, cache, validators, HTTP client
├── tests/
├── pyproject.toml
└── README.md

Key design decisions:

• Async-first: All API calls are fully async with httpx, never blocking
• Rate limiting: Token-bucket limiter per service respects each API's limits
• Smart caching: TTL-based per-namespace cache (1h literature, 7d structures)
• Retry logic: Exponential backoff via tenacity for transient failures
• Validation: Input validation before any network call — never wastes API quota

---

Environment Variables

Variable	Description	Default
NCBI_API_KEY	NCBI API key (increases rate limit to 10/s)	None (3/s)
NVIDIA_BOLTZ2_API_KEY	NVIDIA API key for Boltz-2 structure prediction	None
NVIDIA_EVO2_API_KEY	NVIDIA API key for Evo2-40B DNA generation	None
NVIDIA_NIM_API_KEY	Shared fallback key for both NVIDIA model integrations	None
BIOGRID_API_KEY	BioGRID key for curated interaction queries	None
BIOMCP_TRANSPORT	Transport mode: stdio or http	stdio
BIOMCP_HTTP_PORT	HTTP port for hosted SSE deployments	8080
BIOMCP_SESSION_STORE_DIR	Durable directory for saved sessions	.biomcp_sessions
BIOMCP_AUTH_ENABLED	Require auth for hosted MCP requests	disabled
BIOMCP_OAUTH_ENABLED	Enable OAuth 2.1 PKCE endpoints when auth is enabled	1
BIOMCP_API_KEYS	Comma-separated API keys in key_id:secret form	None
BIOMCP_API_KEY_RATE_LIMIT_REQUESTS	Per-key request budget per window	600
BIOMCP_API_KEY_RATE_LIMIT_WINDOW_SECONDS	Per-key rate-limit window in seconds	60
BIOMCP_OAUTH_AUTO_APPROVE	Auto-approve the consent screen for single-user deployments	0
BIOMCP_OAUTH_DEFAULT_SUBJECT	Subject bound to approved OAuth tokens	heuris-biomcp-user
BIOMCP_CORS_ALLOW_ORIGINS	Comma-separated browser origins allowed for CORS	disabled
BIOMCP_HTTP_RATE_LIMIT_ENABLED	Enable per-client HTTP rate limiting	1
BIOMCP_HTTP_RATE_LIMIT_REQUESTS	Requests allowed per rate-limit window	120
BIOMCP_HTTP_RATE_LIMIT_WINDOW_SECONDS	Rate-limit window length in seconds	60
BIOMCP_HTTP_AUTH_RATE_LIMIT_REQUESTS	Requests allowed per authenticated window	600
BIOMCP_HTTP_AUTH_RATE_LIMIT_WINDOW_SECONDS	Authenticated rate-limit window length in seconds	60
BIOMCP_CACHE_WARMING	Enable background cache warming in HTTP mode	auto
BIOMCP_LOG_LEVEL	Log level: DEBUG/INFO/WARNING/ERROR	INFO

Get free API keys:

• NCBI: https://www.ncbi.nlm.nih.gov/account/
• NVIDIA Boltz-2: https://build.nvidia.com/mit/boltz2
• NVIDIA Evo2-40B: https://build.nvidia.com/arc/evo2-40b
• BioGRID: https://webservice.thebiogrid.org/

Operational Endpoints

When BioMCP runs in hosted HTTP mode, these operational routes are available:

Endpoint	Purpose
/status	Runtime status, HTTP policy, and session-storage configuration
/metrics	Prometheus-compatible request, cache, latency, auth, and upstream metrics
/healthz	Liveness and deployment metadata
/readyz	Readiness check for orchestrators and load balancers
/tool-health	Capability-level status, including missing optional API keys
/.well-known/oauth-authorization-server	OAuth 2.1 metadata for hosted connectors
/oauth/register	Dynamic OAuth client registration
/oauth/authorize	OAuth authorization and PKCE consent
/oauth/token	Authorization-code and refresh-token exchange
/mcp	Streamable HTTP MCP endpoint
/sse	MCP SSE endpoint
/messages/	MCP message transport endpoint

These endpoints are designed for deployment review, Render health checks, and production smoke tests.

---

Contributing

Contributions are welcome! Whether it's adding a new database, fixing a bug, improving documentation, or integrating new AI models.

# Development setup
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --cov=biomcp

# Lint + type check
ruff check src/
mypy src/

Ideas for contributions

• Add more pathway databases (Wikipathways, PathCards)
• Integrate COSMIC for somatic mutations
• Add protein complex data (CORUM)
• Implement batch query support for high-throughput analysis
• Add Jupyter notebook examples
• Improve conflict resolution algorithms

---

Citation

If you use Heuris-BioMCP in your research, please cite:

@software{biomcp2025,
  title   = {Heuris-BioMCP v2: A Comprehensive MCP Server for Bioinformatics, AI Models, and Life Sciences},
  year    = {2025},
  url     = {https://github.com/SachinGawande2003/Heuris-BioMCP},
  license = {MIT}
}

---

License

MIT License — free for academic and commercial use.

---