# AGR MCP Server
MCP server for querying [Alliance of Genome Resources](https://www.alliancegenome.org) - genomics data across model organisms.
## Installation
### Option 1: npx (Recommended)
No installation required. Add to your MCP client config:
```json
{
"mcpServers": {
"agr-genomics": {
"command": "npx",
"args": ["-y", "agr-mcp-server"]
}
}
}
```
### Option 2: Global install
```bash
npm install -g agr-mcp-server
```
Then use in your config:
```json
{
"mcpServers": {
"agr-genomics": {
"command": "agr-mcp-server"
}
}
}
```
### Config file locations
| Client | Config path |
|--------|-------------|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `~/.claude/settings.json` |
| Cursor | Settings > MCP Servers |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
## Usage
Ask questions naturally:
- "Search for BRCA1 genes in human"
- "What genes are involved in DNA repair?"
- "Get information about HGNC:1100"
- "Find orthologs of insulin gene"
- "What diseases are associated with TP53?"
- "Show me expression data for daf-2 in worm"
- "Find all human genes with kinase activity"
- "Query AllianceMine for mouse genes on chromosome 11"
### Supported Species
Human, mouse, rat, zebrafish, fly, worm, yeast, xenopus
## Tools
### AGR API Tools
| Tool | Description |
|------|-------------|
| `search_genes` | Search genes with optional species filter |
| `get_gene_info` | Detailed gene information (symbol, location, synonyms) |
| `get_gene_diseases` | Disease associations for a gene |
| `search_diseases` | Search diseases by name |
| `get_gene_expression` | Expression data across tissues/stages |
| `find_orthologs` | Cross-species homologs |
| `get_gene_phenotypes` | Phenotype annotations |
| `get_gene_interactions` | Molecular and genetic interactions |
| `get_gene_alleles` | Alleles/variants for a gene |
| `search_alleles` | Search alleles by name |
| `get_species_list` | List supported model organisms |
### AllianceMine Tools
| Tool | Description |
|------|-------------|
| `mine_search` | Search AllianceMine for genes, proteins, diseases |
| `mine_query` | Run raw PathQuery XML queries |
| `mine_query_builder` | Build queries using JSON DSL |
| `mine_natural_query` | Natural language query (returns schema for LLM) |
| `mine_list_templates` | List available query templates |
| `mine_run_template` | Run a pre-built query template |
| `mine_get_lists` | Get available gene/protein lists |
| `mine_get_list` | Get contents of a specific list |
| `mine_create_list` | Create a new list (requires auth) |
| `mine_add_to_list` | Add items to a list (requires auth) |
| `mine_delete_list` | Delete a list (requires auth) |
### AllianceMine Query Examples
**Using query builder:**
```
Find human genes with BRCA in symbol:
- from: Gene
- select: primaryIdentifier, symbol, name
- where: organism.shortName = "H. sapiens", symbol CONTAINS "BRCA"
```
**Using templates:**
```
Gene_Alleles - Find alleles for a gene
Gene_DOTerm - Disease annotations for a gene
Gene_GOTerms - GO annotations for a gene
GOTerm_Genes - Find genes by GO term
```
### Authentication
List management operations (`mine_create_list`, `mine_add_to_list`, `mine_delete_list`) require an AllianceMine API token:
```json
{
"mcpServers": {
"agr-genomics": {
"command": "npx",
"args": ["-y", "agr-mcp-server"],
"env": {
"ALLIANCEMINE_TOKEN": "your-token-here"
}
}
}
}
```
## Gene ID Formats
| Species | Format | Example |
|---------|--------|---------|
| Human | `HGNC:*` | `HGNC:1100` |
| Mouse | `MGI:*` | `MGI:95892` |
| Rat | `RGD:*` | `RGD:3889` |
| Zebrafish | `ZFIN:ZDB-GENE-*` | `ZFIN:ZDB-GENE-990415-72` |
| Fly | `FB:FBgn*` | `FB:FBgn0000017` |
| Worm | `WB:WBGene*` | `WB:WBGene00000898` |
| Yeast | `SGD:S*` | `SGD:S000002536` |
| Xenopus | `Xenbase:XB-GENE-*` | `Xenbase:XB-GENE-485905` |
## Data Sources
- [Alliance of Genome Resources API](https://www.alliancegenome.org/api)
- [AllianceMine](https://alliancemine.alliancegenome.org/alliancemine)
## License
MIT
