bam-pileup-mcp: Exposing DNA BAM Format files to LLMs for Analysis

Early Release — this project is in early development and may have significant bugs, incomplete features, or breaking changes without notice. Use with appropriate caution.

A Model Context Protocol (MCP) server written in Rust that accepts a genomic coordinate, queries a BAM file, and returns a text-based pileup representation suitable for reasoning by an LLM.

The server supports two transports:

• stdio (default) — for direct MCP client integration
• HTTP (--sse) — streamable-HTTP MCP transport served by axum, suitable for networked or multi-client use

Example Output

Region: chr7:117,548,920-117,549,070  (150bp window)  BAM: sample.bam

POS   117548920                                            117549070
REF   TGCAATCCGAATCGGCATGCCTACGATTTACGGCATGCATCGAATCGGCAT[A]GCATCGGAATCGCATGCCTACGATTTACGGCATGCATCGAATCGGCATGCCT

R01   .............................................................................................................  + MQ60
R02   ...............................................................[G]............................................ + MQ60
R03          ..........................................................................................             + MQ59
R04   ...............................................................[G]............................................ - MQ60
R05                 ......................................................................                         - MQ58

COV   5x at chr7:117,548,975
      A: 2 (40.0%)  G: 3 (60.0%)
      +strand: 3  -strand: 2
      MQ_mean: 59.4  MQ_min: 58
      Reads shown: 5  Reads filtered (MAPQ): 0  Reads filtered (dup/qcfail): 0

BQ    chr7:117,548,975  (reads spanning query position, sorted by strand)

      Read    Strand   BQ-at-query
      R04     -        38
      R05     -        36
      R01     +        40
      R02     +        37
      R03     +        39
      mean: 38.0   min: 36   max: 40

Requirements

• Sorted, indexed BAM file (.bam + .bam.bai)
• FASTA reference file with index (.fa.gz + .fa.gz.fai + .fa.gz.gzi, or plain .fa + .fa.fai)
• Rust 1.85+ (2024 edition)

Building

cargo build --release

The binary is at target/release/bam_mcp_server.

Usage

bam_mcp_server --bam <PATH> --reference <PATH> [OPTIONS]

Options:
  -b, --bam <PATH>           Path to sorted, indexed BAM file
  -r, --reference <PATH>     Path to FASTA reference (.fai index must exist alongside)
  -w, --window <INT>         Default window half-width in bp around query position [default: 75]
  -d, --max-depth <INT>      Maximum reads to display in pileup [default: 50]
  -q, --min-mapq <INT>       Minimum mapping quality filter [default: 0]
  -Q, --min-baseq <INT>      Minimum base quality to show as uppercase [default: 20]
      --sse <ADDR:PORT>       Run as HTTP MCP server instead of stdio (e.g. 127.0.0.1:8090)
      --allowed-host <HOST>  Allow this Host header value for remote access (repeatable; default: localhost/127.0.0.1/::1)
      --allow-all-hosts      Disable Host header checking entirely — allow any host (HTTP mode only)
      --debug                Write debug output to stderr
      --log-file <PATH>      Write debug log to file instead of stderr
  -h, --help                 Print help
  -V, --version              Print version

All debug/log output goes to stderr. The MCP JSON-RPC protocol uses stdout (stdio mode) or the HTTP response body (HTTP mode).

MCP Tools

query_pileup

Input parameters:

... View full README on GitHub