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

2. Install dependencies:

pip install -r requirements.txt

3. (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

2. Add the server configuration:

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

3. 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.