# Omics AI MCP Server
A Model Context Protocol (MCP) server that enables AI agents to conversationally interact with Omics AI Explorer networks for genomics research and data analysis.
## Overview
This MCP server wraps the functionality of the [omics-ai-python-library](https://github.com/mfiume/omics-ai-python-library) to provide AI agents with seamless access to genomics data across multiple Omics AI Explorer networks including:
- **HiFi Solves** (hifisolves.org) - Long-read sequencing data
- **Neuroscience AI** (neuroscience.ai) - Neuroscience genomics data
- **ASAP** (cloud.parkinsonsroadmap.org) - Aligning Science Across Parkinson's
- **Viral AI** (viral.ai) - Viral genomics and surveillance data
- **Target ALS** (dataportal.targetals.org) - ALS research data
## Features
The MCP server provides the following tools for AI agents:
- **`list_collections`** - Discover available data collections in any network
- **`list_tables`** - Browse tables within specific collections
- **`get_schema_fields`** - Examine table schemas and field types
- **`query_table`** - Query data with filters, pagination, and ordering
- **`count_rows`** - Count rows matching specific criteria
- **`sql_search`** - Execute direct SQL queries using Trino syntax
## Installation
```bash
git clone https://github.com/mfiume/omics-ai-mcp.git
cd omics-ai-mcp
npm install
```
## Usage
### Running the Server
```bash
npm start
```
### Configuration for Claude Desktop
Add to your Claude Desktop configuration file:
```json
{
"mcpServers": {
"omics-ai": {
"command": "node",
"args": ["src/index.js"],
"cwd": "/path/to/omics-ai-mcp"
}
}
}
```
### Example AI Agent Interactions
Once configured, AI agents can conversationally query genomics data:
> **Agent**: "What collections are available on the Viral AI network?"
> **User**: "Show me the tables in the virusseq collection"
> **Agent**: "List the first 10 variants from the variants table where chromosome equals chr1"
> **User**: "How many total variants are in the VirusSeq database?"
## Tool Reference
### list_collections
Lists all available collections in a network.
**Parameters:**
- `network` (required): Network name (hifisolves, viral, neuroscience, etc.) or full URL
- `access_token` (optional): Authentication token
### list_tables
Lists all tables in a specific collection.
**Parameters:**
- `network` (required): Network name or URL
- `collection_slug` (required): Collection identifier (e.g., "virusseq", "gnomad")
- `access_token` (optional): Authentication token
### get_schema_fields
Retrieves the schema and field definitions for a table.
**Parameters:**
- `network` (required): Network name or URL
- `collection_slug` (required): Collection identifier
- `table_name` (required): Qualified table name (e.g., "collections.virusseq.variants")
- `access_token` (optional): Authentication token
### query_table
Queries data from a table with optional filtering and pagination.
**Parameters:**
- `network` (required): Network name or URL
- `collection_slug` (required): Collection identifier
- `table_name` (required): Qualified table name
- `filters` (optional): Filter criteria object
- `limit` (optional): Max rows to return (default: 100)
- `offset` (optional): Rows to skip (default: 0)
- `order_by` (optional): Sort specification
- `access_token` (optional): Authentication token
### count_rows
Counts rows matching specified filters.
**Parameters:**
- `network` (required): Network name or URL
- `collection_slug` (required): Collection identifier
- `table_name` (required): Qualified table name
- `filters` (optional): Filter criteria object
- `access_token` (optional): Authentication token
### sql_search
Executes direct SQL queries against a collection using Trino syntax with enhanced result formatting.
**Parameters:**
- `network` (required): Network name or URL
- `collection_slug` (required): Collection identifier
- `sql` (required): SQL query string (use Trino syntax with double quotes for identifiers)
- `max_polls` (optional): Maximum number of polling attempts (default: 10)
- `poll_interval` (optional): Seconds to wait between polls (default: 2.0)
- `access_token` (optional): Authentication token
**Features:**
- Automatic async query polling with robust error handling
- Intelligent result formatting (table view for simple data, JSON for complex)
- Progress indicators and pagination info
- Timeout management for long-running queries
**Example queries:**
- `SELECT COUNT(*) FROM "schema"."table"`
- `SELECT * FROM "schema"."variants" WHERE chrom = 'chr1' LIMIT 10`
- `SELECT DISTINCT chrom FROM "schema"."variants" ORDER BY chrom`
## Supported Networks
The server supports these pre-configured networks (use short names for convenience):
| Short Name | Full URL | Description |
|------------|----------|-------------|
| hifisolves | hifisolves.org | Long-read sequencing data |
| neuroscience | neuroscience.ai | Neuroscience genomics |
| asap | cloud.parkinsonsroadmap.org | Parkinson's research |
| viral | viral.ai | Viral genomics |
| targetals | dataportal.targetals.org | ALS research |
## Error Handling
The server includes robust error handling for:
- Network connectivity issues
- Authentication failures
- Invalid parameters
- API response parsing errors
- Timeout handling for long-running queries
## Development
```bash
# Development mode with auto-restart
npm run dev
# Production mode
npm start
```
## License
MIT License - see LICENSE file for details.
## Related Projects
- [omics-ai-python-library](https://github.com/mfiume/omics-ai-python-library) - Python client library
- [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP specification and SDKs
