bioinformatics-mcp

🧬 bioinformatics-mcp

A comprehensive MCP server for bioinformatics — enabling AI agents (Claude Desktop, Claude Code, etc.) to run genomics, transcriptomics, epigenetics, and variant analysis workflows through the Model Context Protocol.

📓 Interactive Tutorial Notebook — Full PBMC 3k analysis from raw data to annotated clusters with database lookups

---

Why?

Bioinformatics workflows involve chaining many specialized tools (scanpy, biopython, squidpy, pysam, etc.) with domain-specific knowledge about parameter choices and step ordering. bioinformatics-mcp wraps these tools as MCP endpoints so an AI agent can:

• 🔬 Run complete single-cell RNA-seq pipelines (QC → clustering → markers)
• 🗺️ Analyse spatial transcriptomics (spatial neighbors, autocorrelation, co-occurrence)
• 🧪 Perform differential expression and pathway enrichment analysis
• 🧫 Analyse DNA methylation & epigenetics (CpG islands, DMRs, beta-value distributions)
• 🧬 Parse and analyse FASTA sequences, find ORFs, compute GC content
• 📊 Parse VCF files and compute variant statistics (Ti/Tv ratio, etc.)
• 🌐 Query public databases — NCBI Gene, UniProt, Ensembl, PubMed — with zero config
• 📈 Generate publication-quality plots (UMAP, volcano, dotplot, heatmap, spatial)
• 💾 Manage datasets in-session across multi-step workflows

All through natural language conversation.

Quick Start

Installation

# Core (sequence tools, data I/O, methylation)
pip install bioinformatics-mcp

# With single-cell analysis support
pip install "bioinformatics-mcp[single-cell]"

# With spatial transcriptomics
pip install "bioinformatics-mcp[spatial]"

# With variant analysis
pip install "bioinformatics-mcp[variants]"

# Everything
pip install "bioinformatics-mcp[full]"

Use with Claude Desktop

Add to your claude_desktop_config.json (see examples/):

{
  "mcpServers": {
    "bioinformatics": {
      "command": "python",
      "args": ["-m", "bioinformatics_mcp"],
      "env": {}
    }
  }
}

Use with Claude Code

claude mcp add bioinformatics -- python -m bioinformatics_mcp

Run Standalone

# stdio transport (default, for MCP clients)
python -m bioinformatics_mcp

# Streamable HTTP transport (for web/remote clients)
python -m bioinformatics_mcp --transport streamable-http --port 8000

# SSE transport
python -m bioinformatics_mcp --transport sse --port 8000

Docker

# Build
docker build -t bioinformatics-mcp .                           # full image
docker build --target slim -t bioinformatics-mcp:slim .        # core only

# Run stdio (pipe to MCP client)
docker run -i bioinformatics-mcp

# Run HTTP server
docker run -p 8000:8000 bioinformatics-mcp --transport streamable-http

# Docker Compose (see examples/)
cd examples && docker compose up

Available Tools (70+)

📂 Data I/O

Tool	Description
load_anndata	Load .h5ad files (AnnData format)
load_csv	Load CSV/TSV files as DataFrames
load_10x_mtx	Load 10x Genomics Cell Ranger output
save_anndata	Save datasets to .h5ad
list_datasets	List all loaded datasets
inspect_dataset	Get detailed dataset info
remove_dataset	Free memory by removing datasets

🔬 Quality Control

Tool	Description
calculate_qc_metrics	Compute gene counts, UMI counts, %mito, %ribo
plot_qc_metrics	Violin plots of QC metrics
filter_cells_and_genes	Filter by min/max genes, %mito, min cells
detect_doublets	Scrublet-based doublet detection

⚙️ Preprocessing & Clustering

Tool	Description
normalize_and_log	Library size normalization + log1p
find_highly_variable_genes	HVG selection (Seurat v3, etc.)
scale_data	Zero-mean unit-variance scaling
run_pca	Principal Component Analysis
compute_neighbors	k-NN graph construction
run_umap	UMAP embedding
run_leiden_clustering	Leiden community detection
run_standard_pipeline	All of the above in one step

📊 Differential Expression

Tool	Description
rank_genes_groups	Wilcoxon / t-test DE between groups
get_marker_genes	Extract filtered markers for a group

🧪 Enrichment Analysis

Tool	Description
run_enrichment_analysis	ORA via Enrichr (GO, KEGG, Reactome, etc.)
run_gsea_preranked	Pre-ranked GSEA from DE results

🏷️ Cell Type Annotation

Tool	Description
annotate_cell_types	Auto-label clusters using marker gene panels (PBMC, tumor, mouse)
list_marker_panels	Browse available marker panels and their genes

🔧 Dataset Operations

Tool	Description
subset_dataset	Filter cells by any .obs column (pandas query syntax)
merge_datasets	Concatenate multiple datasets with batch tracking
rename_clusters	Relabel clusters (e.g. '0' → 'CD4+ T cells')
export_obs_table	Export .obs metadata as CSV
export_gene_expression	Extract expression values for specific genes

🗺️ Spatial Transcriptomics

Tool	Description
compute_spatial_neighbors	Build spatial neighbor graph from coordinates
spatial_autocorrelation	Moran's I / Geary's C for spatially variable genes
neighborhood_enrichment	Test cluster co-localisation in tissue
co_occurrence	Cluster co-occurrence at increasing distances
ripley_score	Ripley's F/G/L spatial point pattern statistics
plot_spatial	Plot expression or clusters on tissue coordinates
plot_spatial_nhood_enrichment	Neighborhood enrichment heatmap

🧫 Methylation & Epigenetics

Tool	Description
parse_bedgraph	Parse bedGraph methylation tracks
parse_methylation_table	Load tabular methylation calls (Bismark, nanome, etc.)
methylation_summary_by_chromosome	Per-chromosome methylation statistics
find_differentially_methylated_regions	Sliding-window DMR detection between groups
cpg_density	CpG observed/expected ratio & island classification
plot_methylation_distribution	Beta-value histogram (optional group overlay)

🌐 Public Database Connectors (zero config, no API keys)

Tool	Description
search_ncbi_gene	Search NCBI Gene by symbol/name/keyword
fetch_ncbi_gene_details	Full gene info: summary, location, OMIM, exon count
search_ncbi_nucleotide	Search NCBI Nucleotide database
fetch_ncbi_sequence	Download FASTA/GenBank by accession
search_uniprot	Protein search (Swiss-Prot/TrEMBL, organism filter)
fetch_uniprot_entry	Full protein details: function, domains, GO, sequence
search_ensembl_genes	Gene lookup with Ensembl ID and transcript info
fetch_ensembl_sequence	Download genomic/cDNA/CDS sequence by Ensembl ID
search_pubmed	Literature search with structured results
fetch_pubmed_abstract	Full abstract, authors, MeSH terms, keywords
fetch_gene_ontology	GO annotations grouped by BP/MF/CC
search_clinvar	Clinical variants by gene + pathogenicity filter
get_protein_interactions	Protein–protein interactions from STRING
get_string_enrichment	Functional enrichment (GO, KEGG) for gene sets via STRING

🧬 Sequence Tools

Tool	Description
parse_fasta	Parse FASTA files with sequence summaries
gc_content	Compute GC% of a sequence
translate_sequence	DNA → protein translation
reverse_complement	Get reverse complement
find_orfs	Find open reading frames
bam_stats	BAM/SAM alignment statistics

🔍 Variant Tools

Tool	Description
parse_vcf	Parse VCF files with variant details
vcf_summary_stats	Variant type counts, Ti/Tv ratio, chr distribution

📈 Visualization

Tool	Description
plot_umap	UMAP scatter plots
plot_dotplot	Gene expression dot plots
plot_heatmap	Expression heatmaps
plot_volcano	Volcano plots from DE results
plot_marker_genes	Top markers per cluster

Guided Workflows (MCP Prompts)

The server includes pre-built prompts that guide agents through multi-step analyses:

Prompt	Description
scrna_standard_analysis	Complete scRNA-seq from raw data to annotated clusters
differential_expression_workflow	DE analysis with enrichment
spatial_transcriptomics_workflow	Spatial analysis: neighbors → autocorrelation → co-occurrence
methylation_analysis_workflow	Methylation: distribution → per-chrom → DMRs → CpG islands
variant_analysis_workflow	VCF analysis and interpretation
sequence_analysis_workflow	FASTA analysis with ORF finding
gene_research_workflow	Multi-database gene research (NCBI → UniProt → Ensembl → PubMed)

Example Conversation

You: Load the PBMC dataset at ~/data/pbmc3k.h5ad and run a standard single-cell analysis.

Claude: I'll load the data and run the complete pipeline... (calls load_anndata → run_standard_pipeline → plot_umap → rank_genes_groups → plot_marker_genes)

The analysis found 8 clusters. Based on marker genes:

• Cluster 0: CD4+ T cells (IL7R, CD4)
• Cluster 1: CD14+ Monocytes (CD14, LYZ)
• Cluster 2: B cells (MS4A1, CD79A)
• ...

Architecture

bioinformatics-mcp/
├── src/bioinformatics_mcp/
│   ├── server.py              # FastMCP server + tool registration
│   ├── __main__.py            # CLI entry point (stdio / sse / streamable-http)
│   ├── tools/                 # Tool modules (auto-register via decorators)
│   │   ├── data_io.py         # Load/save/inspect datasets
│   │   ├── quality_control.py # QC metrics and filtering
│   │   ├── preprocessing.py   # Normalize, HVG, PCA, cluster
│   │   ├── differential_expression.py
│   │   ├── gene_set_enrichment.py
│   │   ├── databases.py       # NCBI, UniProt, Ensembl, PubMed connectors
│   │   ├── spatial.py         # Squidpy-based spatial analysis
│   │   ├── methylation.py     # CpG, DMRs, beta-value analysis
│   │   ├── sequence_tools.py  # FASTA, ORFs, GC content
│   │   ├── variant_tools.py   # VCF parsing and stats
│   │   └── visualization.py   # UMAP, volcano, dotplot, heatmap
│   ├── models/                # Pydantic data models
│   ├── resources/             # MCP Resources (dataset browsing)
│   ├── prompts/               # MCP Prompts (workflow guides)
│   └── utils/                 # DataManager, plotting, imports
├── tests/
│   ├── tools/                 # Unit tests per module
│   └── integration/           # End-to-end workflow tests
├── notebooks/
│   └── pbmc3k_tutorial.ipynb  # 📓 Full PBMC 3k tutorial notebook
├── examples/
│   ├── quickstart.py          # Direct Python usage example
│   ├── claude_desktop_config.json
│   └── docker-compose.yml
├── .github/workflows/
│   ├── ci.yml                 # Lint + test + typecheck + Docker build
│   └── publish.yml            # PyPI trusted publishing on release
├── Dockerfile                 # Multi-stage: slim / full
├── pyproject.toml
└── README.md

Key design decisions:

• Session DataManager — datasets live in memory across tool calls, enabling multi-step workflows
• Lazy imports — heavy deps (scanpy, squidpy, pysam) only load when their tools are called
• Optional extras — install only what you need ([single-cell], [spatial], [variants], [full])
• Multiple transports — stdio (default), SSE, and Streamable HTTP for flexible deployment
• Base64 plots — visualisations are returned as base64 PNGs, compatible with MCP image content
• Multi-stage Docker — slim image for core tools, full image with everything

Development

We provide a Makefile for common tasks:

make dev          # install with all deps + dev tools
make test         # run tests
make lint         # run linter + format check
make serve        # start MCP server (stdio)
make serve-http   # start MCP server (HTTP on port 8000)
make docker       # build Docker image
make help         # show all targets

Or manually:

git clone https://github.com/raonyguimaraes/bioinformatics-mcp
cd bioinformatics-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[full,dev]"

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Format code
ruff format src/ tests/

# Type check
mypy src/bioinformatics_mcp/ --ignore-missing-imports

# Run the quickstart example
python examples/quickstart.py

Contributing

Contributions welcome! Areas where help is especially valuable:

• 🧬 New tool modules — long-read analysis, proteomics, phylogenetics
• 📊 More visualisations — interactive plots, genome browsers
• 🔧 Workflow prompts — guided analysis templates for common use cases
• 📖 Documentation — tutorials, example notebooks
• 🧪 Tests — more coverage, integration tests with real datasets
• 🌍 Translations — non-English documentation

License

MIT — see LICENSE.