BV-BRC MCP Server

mcp-bvbrc

A Model Context Protocol (MCP) server for interacting with the BV-BRC (Bacterial and Viral Bioinformatics Resource Center) API. This server provides tools for querying and retrieving genomic data, features, antimicrobial resistance data, epitopes, and more.

Overview

BV-BRC is a comprehensive bioinformatics resource for bacterial and viral pathogen data. This MCP server exposes the BV-BRC API through a set of tools that can be used with Claude and other MCP-compatible applications.

Key Features

• Query Genomes: Search and retrieve genome data with filters for organism, strain, and more
• Genomic Features: Query genes, proteins, RNA molecules, and other genomic features
• Antimicrobial Resistance: Access AMR data and resistance mechanisms
• Epitopes & Assays: Retrieve vaccine target and epitope assay data
• Advanced Queries: Use RQL (Relational Query Language) for complex data queries
• Multiple Data Types: Access 13+ different data types in the BV-BRC database

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)

Quick Start

1. Clone or download this repository:

git clone https://github.com/soham-shukla/mcp-bvbrc.git
cd mcp-bvbrc

1. Install dependencies:

pip install -r requirements.txt

1. (Optional) Install in development mode with additional tools:

pip install -e ".[dev]"

Configuration

For Claude Desktop

The easiest way to use this server is with Claude Desktop:

1. Find your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Add the server configuration:

{
  "mcpServers": {
    "bvbrc": {
      "command": "python",
      "args": ["/absolute/path/to/bvbrc.py"]
    }
  }
}

1. Restart Claude Desktop

See CONFIG.md for more configuration options.

Available Tools

1. query_data_type

Perform advanced queries on any BV-BRC data type using RQL syntax.

Parameters:

• data_type (required): The data type to query (e.g., genome, genome_feature, epitope)
• query (optional): RQL query string
• limit (optional, default: 10): Maximum results to return
• offset (optional, default: 0): Results to skip

Example: `` Query genomes of Salmonella with organism name and genome size data_type: "genome" query: "eq(organism,Salmonella)&select(genome_id,organism,dna_size)" limit: 5 ``

2. get_record_by_id

Retrieve a specific record by its ID.

Parameters:

• data_type (required): The data type (e.g., genome, genome_feature)
• record_id (required): The ID of the record

Example: `` Get genome with ID "1234567.890" data_type: "genome" record_id: "1234567.890" ``

3. search_genomes

Search for genomes with convenient filtering.

Parameters:

• organism (optional): Filter by organism name
• genome_id (optional): Filter by genome ID
• strain (optional): Filter by strain
• limit (optional, default: 10): Maximum results
• offset (optional, default: 0): Results to skip

Example: `` Search for Escherichia coli genomes organism: "Escherichia coli" limit: 20 ``

4. search_features

Search for genomic features (genes, proteins, etc.) with filtering.

Parameters:

• genome_id (optional): Filter by genome ID
• feature_type (optional): Filter by type (e.g., CDS, RNA)
• keyword (optional): Keyword search
• limit (optional, default: 10): Maximum results
• offset (optional, default: 0): Results to skip

Example: `` Search for CDS features in a genome genome_id: "1234567.890" feature_type: "CDS" limit: 50 ``

5. get_available_data_types

Get information about all available data types in BV-BRC.

Returns: List of data types with descriptions and common fields.

Supported Data Types

| Data Type | Description | Primary Key | |-----------|-------------|------------| | genome | Genome records with assembly and taxonomy | genome_id | | genome_feature | Genomic features (genes, proteins, RNA) | feature_id | | strain | Strain information and metadata | strain_id | | genome_amr | Antimicrobial resistance data | genome_id | | epitope | Epitope data including vaccine targets | epitope_id | | epitope_assay | Epitope assay results | assay_id | | experiment | Experiment metadata and results | experiment_id | | bioset | Collection of genomes | bioset_id | | bioset_result | Results associated with biosets | result_id | | feature_sequence | Nucleotide and protein sequences | feature_id | | antibiotics | Antibiotic information database | antibiotic_id | | enzyme_class_ref | Enzyme classification reference | enzyme_class_id | | gene_ontology_ref | Gene Ontology reference data | go_id |

RQL Query Syntax

The BV-BRC API uses RQL (Relational Query Language) for advanced queries. Here are common operators:

Comparison Operators

• eq(field,value) - Field equals value
• ne(field,value) - Field not equal to value
• gt(field,value) - Field greater than value
• lt(field,value) - Field less than value
• in(field,(value1,value2)) - Field contains any of the values

Logical Operators

• and(expr1,expr2,...) - AND expressions together
• or(expr1,expr2,...) - OR expressions together

Query Modifiers

• keyword(value) - Full-text search
• select(field1,field2) - Return only specified fields
• sort([+|-]field) - Sort results (+ ascending, - descending)
• limit(count,offset) - Limit and offset results

Examples

Find Salmonella genomes with specific fields: `` eq(organism,Salmonella)&select(genome_id,organism,strain,dna_size)&limit(10,0) ``

Search for antibiotic-resistant Salmonella: `` and(eq(organism,Salmonella),eq(amr_phenotype,resistant))&select(genome_id,organism,antibiotic)&limit(20,0) ``

Full-text search across features: `` keyword(virulence)&select(feature_id,product)&limit(15,0) ``

Python Usage

You can also use the server programmatically:

import asyncio
from client import BVBRCClient

async def main():
    client = BVBRCClient()
    
    # Query genomes
    results = await client.query(
        "genome",
        "eq(organism,Salmonella)&select(genome_id,organism)",
        limit=10
    )
    
    # Get a specific record
    record = await client.get_by_id("genome", "1234567.890")

asyncio.run(main())

Error Handling

The server handles common errors gracefully:

• Invalid data types: Returns error message
• Network errors: Returns connection error details
• Invalid queries: API returns error information
• Missing records: Returns 404 error message

Performance Considerations

• Default limit is 10 records; use offset for pagination
• Large result sets may take longer to retrieve
• Use specific filters to reduce result size
• RQL queries are optimized server-side for efficiency

Authentication

The BV-BRC public API requires no authentication. However, if you have private data access:

1. Set the BVBRC_API_TOKEN environment variable with your token
2. The client will automatically include it in requests

export BVBRC_API_TOKEN="your-token-here"
python bvbrc.py

API Documentation

For complete BV-BRC API documentation, visit:

• BV-BRC API Documentation
• BV-BRC Website
• BV-BRC Command Line Interface

Architecture

The server consists of three main modules:

• bvbrc.py: Main MCP server with tool definitions and orchestration
• client.py: HTTP client for BV-BRC API interactions
• data_types.py: Data type definitions and metadata

Development

Running Tests

pytest tests/

Code Style

black bvbrc.py client.py data_types.py
isort bvbrc.py client.py data_types.py

Type Checking

mypy bvbrc.py client.py data_types.py

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues with this MCP server, please open a GitHub issue.

For questions about the BV-BRC API itself, visit the BV-BRC help documentation.

---

Note: This MCP server is an independent tool and is not officially affiliated with or endorsed by BV-BRC.