genome-mcp - "Ask your genome" through the Model Context Protocol

genome-mcp turns a VCF file (the standard output of DNA sequencing pipelines) into a set of MCP tools that any AI assistant can call. Plug it into Claude Desktop, Cursor, VS Code or your own agent and ask in plain English:

"Do I carry anything in BRCA1?" · "Am I a carrier for any disease?" · "Is warfarin a concern for me?" · "What's my APOE status?"

The model doesn't guess from memory - it calls real tools that read your file, match variants against curated annotations, and apply genetics rules (zygosity, carrier vs affected, APOE haplotypes, pharmacogenomics), then explains the result simply.

Note: educational project. Not a medical device, not medical advice. The bundled sample is synthetic.

Why this is interesting

• Bioinformatics × AI agents. Most genomics tools are command-line programs for specialists. MCP lets an LLM use them safely: the LLM handles language, the tools handle facts.

• No hallucinated genetics. Every answer comes from a tool result with the genotype, the source and a disclaimer.

• Domain logic, not just lookups. It knows that one copy of a CFTR variant usually means carrier, while one copy of a BRCA1 variant raises risk; it derives APOE ε2/ε3/ε4 from two SNPs; it ignores low-quality calls.

• Standard protocol. Built on the official MCP Python SDK, so it works with any MCP client.

Related MCP server: GenomeMCP

How it works

 You ──question──► MCP client (Claude Desktop / genome-mcp ask / your agent)
                          │  list_tools, call_tool   (JSON-RPC over stdio)
                          ▼
                 genome-mcp server  ── tools ───────────────────────────────┐
                          │                                                 │
       ┌──────────────────┼──────────────────┬──────────────────┐           │
       ▼                  ▼                  ▼                  ▼           │
  VCF reader        Gene index        ClinVar snapshot     Live APIs       │
  (streams .vcf,    (GRCh38 coords,   (curated pathogenic,  (Ensembl,      │
   .vcf.gz, GT,      binary search)    risk, PGx variants)   MyVariant;    │
   zygosity, QC)                                             optional)     │
                          └──────────► JSON result + disclaimer ◄──────────┘

Quick start

git clone https://github.com/Noella-John1997/genome-mcp.git
cd genome-mcp
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

genome-mcp report                              # full markdown report on the demo sample
genome-mcp ask "Am I a carrier for any disease?"   # starts the MCP server and calls a tool
genome-mcp ask "What is my APOE status?"
pytest -q                                      # run the tests

Use your own file: add --vcf path/to/file.vcf (or .vcf.gz) to any command. Coordinates must be GRCh38.

Web app

genome-mcp web           # open http://127.0.0.1:8000

Use the synthetic demo sample or upload your own .vcf / .vcf.gz (≤ 20 MB, GRCh38). Ask a question in plain English and the page shows which MCP tool was called with which arguments, a friendly answer, and the raw JSON the AI model would receive. Below: QC tiles, clinically relevant findings with a plain-language interpretation (carrier vs raised risk), APOE, medicines, and a gene explorer.

Put it online for free (Render or Hugging Face Spaces): see deploy/. Live demo: https://genome-mcp.onrender.com (replace with your URL)

Use it from Claude Desktop

1. Find the full path of the installed command: which genome-mcp (Windows: where genome-mcp).

2. Open Claude Desktop → Settings → Developer → Edit Config, and add (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "genome": {
      "command": "/full/path/to/.venv/bin/genome-mcp",
      "args": ["serve"]
    }
  }
}

3. Restart Claude Desktop and ask: "Use the genome tools: do I carry anything in BRCA1?"

Let an LLM pick the tools from the command line

export OPENAI_API_KEY=sk-...          # any OpenAI-compatible endpoint; set OPENAI_BASE_URL to change
genome-mcp ask "Explain my pharmacogenomic results for a doctor" --llm

Tools

Resource: genome://genes lists the genes the server knows.

What the demo sample shows

See examples/sample_report.md. The synthetic sample is a heterozygous carrier of pathogenic variants in HFE (hemochromatosis) and CFTR (cystic fibrosis), carries a BRCA1 frameshift, is APOE ε3/ε4, and has several pharmacogenomic variants. One CYP2C9 call is marked LowQual - the tools skip it, as a real pipeline should.

Commands

Project layout

Genetics glossary (for non-biologists)

Limitations

• The annotation snapshot is a small curated set (~15 well-known variants), not all of ClinVar. For real use, annotate with VEP / ANNOVAR / SnpEff or load a full ClinVar VCF.

• Indel matching is exact-allele; unnormalised indels (different left-alignment) may not match.

• APOE uses unphased data and assumes absent sites are reference.

• No CNV / structural-variant support.

Roadmap

Full ClinVar VCF index (tabix) · VEP integration · Nextflow pipeline from FASTQ to this server · star-allele calling for CYP2D6 · HTTP (streamable) MCP transport.

License

MIT - see LICENSE.