AI-powered genomic intelligence through the Model Context Protocol
GenomeMCP is a research-grade Model Context Protocol (MCP) server that enables AI agents to query clinical genomics databases, retrieve supporting scientific literature, analyze population genetics, and visualize biological pathways — all in real-time.
GenomeMCP includes a beautiful command-line interface with rich formatting and an interactive TUI mode.
# Recommended (any platform with Python)
pipx install genomemcp
# macOS (Homebrew)
brew install nexisdev/tap/genomemcp
# Windows (Scoop)
scoop bucket add genomemcp https://github.com/nexisdev/scoop-genomemcp
scoop install genomemcp
# From source
git clone https://github.com/nexisdev/GenomeMCP.git
cd GenomeMCP && ./install.shStandalone binaries available on GitHub Releases.
genomemcp search BRCA1 # 🔍 Search ClinVar
genomemcp variant 12345 # 📋 Get variant report
genomemcp gene TP53 # 🧬 Get gene info
genomemcp pathway EGFR --visualize # 🔬 Pathway analysis
genomemcp population 1-55516888-G-GA # 👥 gnomAD frequencies
genomemcp discover "Lynch Syndrome" # 🔗 Discover related genes
genomemcp tui # 🖥️ Interactive modegenomemcp --theme cyberpunk search BRCA1
genomemcp --theme professional gene TP53
genomemcp --theme minimal pathway EGFRSee CLI Guide for complete documentation.
| Problem | GenomeMCP Solution |
|---|---|
| AI agents lack genomic knowledge | Direct ClinVar, gnomAD, Reactome integration |
| No evidence for clinical claims | Auto-retrieves PubMed abstracts |
| Variant interpretation is complex | Population frequency + pathway context |
| Gene-disease links are opaque | Automatic relationship discovery |
search_clinvar(term)— Query ClinVar for genes, variants, or diseasesget_variant_report(id)— Detailed clinical significance reportget_gene_info(symbol)— Gene function, location, and aliases from NCBI Geneget_supporting_literature(id)— PubMed articles linked to a variant
get_population_stats(variant)— Allele frequency from gnomAD (Genome Aggregation Database)
get_pathway_info(gene)— Reactome biological pathways for a genevisualize_pathway(gene)— Generate Mermaid.js diagrams of gene-pathway relationships
find_related_genes(phenotype)— Discover genes associated with a diseaseget_genomic_context(gene, position)— Identify exon vs intron regionsget_discovery_evidence(phenotype)— Aggregate PubMed abstracts for AI reasoning
# Clone the repository
git clone https://github.com/nexisdev/GenomeMCP.git
cd GenomeMCP
# Install dependencies with uv
uv sync
# Run the MCP server
uv run python src/main.py# Using the install script
./install.sh
# Or with pip
pip install genomemcp[cli]
# Or for development
./setup-dev.sh
source .venv/bin/activateAdd to your claude_desktop_config.json:
{
"mcpServers": {
"genomemcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/GenomeMCP",
"run",
"python",
"src/main.py"
]
}
}
}
### ☁️ Cloud Deployment (Railway)
You can deploy the GenomeMCP server to the cloud with one click. It will be exposed as an SSE (Server-Sent Events) endpoint, ready for remote agents.
1. Click the **Deploy on Railway** button above.
2. Provide your `SUPABASE_URL` and `SUPABASE_KEY` (optional, for persistence).
3. Connect your agent to the deployment URL (e.g. `https://your-app.up.railway.app/sse`).
---
## 📖 Usage Examples
### Search for a Gene Variant
User: "What variants are associated with BRCA1?" Agent uses: search_clinvar("BRCA1")
### Get Population Frequency
User: "How common is the variant 1-55516888-G-GA?" Agent uses: get_population_stats("1-55516888-G-GA") → Returns gnomAD allele frequency: 0.000123 (0.01%)
### Discover Gene-Disease Relationships
User: "What genes are linked to Lynch Syndrome?" Agent uses: find_related_genes("Lynch Syndrome") → Returns: MSH2 (12 variants), MLH1 (8 variants), PMS2 (5 variants)
### Visualize Pathways
User: "Show me the pathways for TP53" Agent uses: visualize_pathway("TP53") → Returns Mermaid diagram:
```mermaid
graph TD
TP53((TP53))
TP53 --> P_123["Transcriptional Regulation by TP53"]
TP53 --> P_456["Cell Cycle Checkpoints"]
TP53 --> P_789["DNA Damage Response"]
| Source | Description | API |
|---|---|---|
| ClinVar | Clinical variant interpretations | NCBI E-utilities |
| gnomAD | Population allele frequencies | gnomAD GraphQL |
| Reactome | Biological pathway database | Reactome Content Service |
| PubMed | Scientific literature | NCBI E-utilities |
| NCBI Gene | Gene annotations | NCBI E-utilities |
GenomeMCP/
├── src/
│ ├── main.py # MCP server & tool definitions
│ ├── clinvar.py # ClinVar & PubMed API client
│ ├── genomics.py # Exon/Intron mapping
│ ├── population.py # gnomAD integration
│ ├── pathways.py # Reactome integration
│ ├── utils.py # Shared utilities
│ └── cli/ # Command-line interface
│ ├── app.py # Typer CLI application
│ ├── formatters/ # Rich output formatters
│ ├── tui/ # Textual interactive UI
│ └── config.py # Theme configuration
├── tests/ # Unit tests
├── docs/ # Documentation
├── install.sh # Quick install script
├── setup-dev.sh # Development setup
└── pyproject.toml # Project configuration
# Run all tests
uv run pytest
# Run CLI tests
uv run pytest tests/test_cli.py -v
# Run specific test suite
uv run pytest tests/test_phase4.py tests/test_phase5.py- CLI Guide — Command-line interface documentation
- Tool Reference — Complete API documentation
- Architecture Guide — System design
Contributions are welcome! Please open an issue or submit a pull request.
MIT License — see LICENSE for details.
genomics bioinformatics clinvar gnomad mcp model-context-protocol ai-agent claude variant-interpretation population-genetics reactome pathway-analysis pubmed ncbi gene-discovery clinical-genomics precision-medicine llm-tools cli tui terminal
Built for AI agents. Powered by open genomic data.
