bio-mcp-bwa

MCP (Model Context Protocol) server for the BWA (Burrows-Wheeler Aligner) sequence alignment tool.

Overview

This MCP server provides access to BWA functionality, allowing AI assistants to perform alignment of short and long sequencing reads to a reference genome.

Features

• bwa_index: Create an index for a reference genome.
• bwa_mem: Align reads using the BWA-MEM algorithm.
• bwa_aln: Find SA coordinates with the BWA-backtrack algorithm.
• bwa_samse: Generate single-end alignments in SAM format.
• bwa_sampe: Generate paired-end alignments in SAM format.
• Support for large reference genomes and read files.

Installation

Prerequisites

• Python 3.9+
• BWA installed (bwa)

Install BWA

# macOS
brew install bwa

# Ubuntu/Debian
sudo apt-get install bwa

# From conda
conda install -c bioconda bwa

Install the MCP server

git clone https://github.com/bio-mcp/bio-mcp-bwa
cd bio-mcp-bwa
pip install -e .

Configuration

Add to your MCP client configuration (e.g., Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bio-bwa": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/bio-mcp-bwa"
    }
  }
}

Environment Variables

• BIO_MCP_MAX_FILE_SIZE: Maximum input file size in bytes (default: 50GB)
• BIO_MCP_TIMEOUT: Command timeout in seconds (default: 3600)
• BIO_MCP_BWA_PATH: Path to BWA executable (default: finds in PATH)
• BIO_MCP_TEMP_DIR: Temporary directory for processing

Usage

Once configured, the AI assistant can use the following tools:

bwa_index - Create BWA Index

Create a BWA index for a reference genome.

Parameters:

• reference_fasta (required): Path to the reference FASTA file.
• algorithm: Indexing algorithm (bwtsw or is). Defaults to bwtsw for genomes >2GB.

bwa_mem - Align with BWA-MEM

Align reads using the BWA-MEM algorithm.

Parameters:

• reference (required): Path to the indexed reference genome.
• reads1 (required): Path to the first reads file (FASTQ).
• reads2: Path to the second reads file for paired-end alignment.
• threads: Number of threads to use (default: 4).
• min_seed_length: Minimum seed length (default: 19).
• band_width: Band width for banded alignment (default: 100).
• read_group: Read group header line.

bwa_aln - Find SA Coordinates

Find SA coordinates with the BWA-backtrack algorithm.

Parameters:

• reference (required): Path to the indexed reference genome.
• reads (required): Path to the reads file (FASTQ).
• threads: Number of threads to use (default: 4).
• max_mismatches: Maximum number of mismatches (default: 4).
• max_gap_opens: Maximum number of gap opens (default: 1).

bwa_samse - Generate Single-End SAM

Generate alignments in SAM format for single-end reads.

Parameters:

• reference (required): Path to the indexed reference genome.
• sai_file (required): Path to the .sai file from bwa_aln.
• reads (required): Path to the original reads file.

bwa_sampe - Generate Paired-End SAM

Generate alignments in SAM format for paired-end reads.

Parameters:

• reference (required): Path to the indexed reference genome.
• sai_file1 (required): Path to the .sai file for read 1.
• sai_file2 (required): Path to the .sai file for read 2.
• reads1 (required): Path to the reads file 1.
• reads2 (required): Path to the reads file 2.

Examples

Index a reference genome

Create a BWA index for the file hg38.fasta.

Align paired-end reads

Align the paired-end reads from r1.fastq and r2.fastq to the hg38 reference genome using BWA-MEM.

Development

Running tests

pytest tests/

Building Docker image

docker build -t bio-mcp-bwa .

License

MIT License