README.md

---
title: BioMCP Explorer
emoji: 🧬
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "6.11.0"
app_file: app.py
pinned: false
short_description: Explore genes, variants, drugs, trials & more
---

# BioMCP Explorer — Gradio App

A feature-rich Gradio web interface for exploring all BioMCP tools and features.
Search, discover, and analyze biomedical data across 13+ entity types and 30+ upstream APIs.

## Quick Start

### 1. Install BioMCP CLI

```bash
uv tool install biomcp-cli
# or: pip install biomcp-cli
```

### 2. Install Python dependencies

```bash
pip install -r requirements.txt
```

### 3. Configure API keys (optional)

Copy `.env.example` to `.env` and fill in your keys. Or enter them in the Settings tab at runtime.

### 4. Launch

```bash
python app.py
```

Open http://localhost:7860 in your browser.

## Tabs Overview

| Tab | Purpose |
|-----|---------|
| ⚙️ Settings & Health | API keys, health checks, version info |
| 🔍 Discover | Free-text concept resolution |
| 🔎 Search | Entity search across 13 types (gene, variant, article, trial, drug, disease, pathway, protein, adverse-event, pgx, gwas, phenotype, cross-entity) |
| 📋 Get Detail | Focused entity detail with selectable sections |
| 🔗 Cross-Entity Helpers | 20 pivot commands between related entities |
| 🧬 Enrichment | g:Profiler gene-set enrichment |
| 📦 Batch | Parallel get calls for up to 10 IDs |
| 📊 Study Analytics | Local cBioPortal study analysis (query, cohort, survival, compare, co-occurrence) |

## API Keys

All optional — BioMCP works without them at reduced rate/features:

| Key | Purpose |
|-----|---------|
| `NCBI_API_KEY` | Better PubMed/PubTator rate limits |
| `S2_API_KEY` | Faster Semantic Scholar access |
| `ONCOKB_TOKEN` | OncoKB variant therapy evidence |
| `OPENFDA_API_KEY` | Better OpenFDA rate limits |
| `NCI_API_KEY` | NCI CTS trial search |
| `DISGENET_API_KEY` | DisGeNET gene-disease scores |
| `UMLS_API_KEY` | Clinical crosswalk in discover |
| `ALPHAGENOME_API_KEY` | Variant effect predictions |

## Requirements

- Python 3.11+
- `biomcp` CLI on PATH
- Gradio 5.x