bvbrc-mcp

Tools that let a language model work with BV-BRC (the Bacterial and Viral Bioinformatics Resource Center): search its data, read and summarize files in a user's workspace, build genome and feature groups, find and submit analysis workflows, look up jobs and their outputs, and search the BV-BRC documentation and the literature. Usable as a Python library or through the MCP servers in this package.

Install

pip install "bvbrc-mcp[server]"     # library + MCP servers
pip install "bvbrc-mcp[server,pdf,xlsx]"   # + PDF text extraction, spreadsheet metadata

Python 3.11 or newer.

Use with an MCP client

stdio (a client that starts the server itself, such as Claude Desktop):

{
  "mcpServers": {
    "bvbrc": {
      "command": "bvbrc-mcp-stdio",
      "env": {"KB_AUTH_TOKEN": "<your BV-BRC token>"}
    }
  }
}

HTTP with OAuth sign-in through BV-BRC: bvbrc-mcp-http (see DEPLOYMENT.md). The public server is https://www.bv-brc.org/mcp.

Use as a library

from bvbrc_mcp import TOOLS, ToolContext, dispatch

ctx = ToolContext(bvbrc_auth_token=token, gowe_url="http://localhost:7000")
result = await dispatch("search_data",
                        {"collection": "genome", "query": 'genome_name:"Mycobacterium tuberculosis"'},
                        ctx)

TOOLS lists every tool with its JSON schema (OpenAI function-calling form), so it can be handed to any model that calls tools. dispatch always returns a dict; failures come back as {"error": ..., "errorType": ...}.

Tools

Area	Tools
Data	search_data, facet_query, probe_data, list_collections, get_collection_fields
Workspace	workspace_browse, get_file_metadata, read_file_preview, search_file, summarize_file, list_samples
Workflows	list_gowe_workflows, get_workflow_inputs, submit_gowe_job, rerun_jobs, prepare_batch
Groups	create_group, edit_group, list_groups, get_group_ids
Jobs	list_jobs, get_job_details, get_expected_outputs
Other	get_sra_metadata, find_similar_genomes, search_literature, query_helpdesk, list_services, get_service_schema

Over MCP each is named agent_<name>. submit_gowe_job, create_group and edit_group change the user's account (bvbrc_mcp.SIDE_EFFECT_TOOLS); a caller should confirm them with the user. rerun_jobs and prepare_batch only prepare jobs.

Workflow tools need a GoWe server (gowe_url). get_sra_metadata needs sra-tools in a Singularity container (sra_container_path) and is unavailable without one.

Configuration

The servers read BVBRC_MCP_CONFIG (a JSON file, see config.example.json) and BVBRC_MCP_<NAME> environment variables; see src/bvbrc_mcp/settings.py for every setting.

Development

python3.11 -m venv .venv && .venv/bin/pip install -e ".[server,pdf,xlsx,dev]"
.venv/bin/pytest

License

MIT