<p align="center"> <img src="logo.jpg" alt="BioVis-MCP Logo" width="600"> </p>

<p align="center"> <a href="https://pypi.org/project/biovis-mcp/"> <img src="https://img.shields.io/pypi/v/biovis-mcp.svg" alt="PyPI Version"> </a> <a href="https://pypi.org/project/biovis-mcp/"> <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python Versions"> </a> <a href="https://pypi.org/project/biovis-mcp/"> <img src="https://img.shields.io/pypi/l/biovis-mcp.svg" alt="License"> </a> </p>

🧬 BioVis-MCP: Automated Bioinformatics Visualization

"From raw data to publication-ready figures in seconds."

BioVis-MCP is a high-performance Model Context Protocol (MCP) server that empowers Large Language Models (like Claude) with the ability to generate publication-quality (300 DPI) bioinformatics visualizations directly from raw biological data.

No more manual Matplotlib tweaking. Just send the data, and get a verified, manuscript-ready image path.

---

✨ Features (Phases 1-3)

📊 Visualization Suite

• Volcano Plots: High-resolution visualization of differential expression, with automated significance highlighting (Up/Down regulated).
• PCA Plots: Principal Component Analysis for sample relationship and variance insights.
• Expression Heatmaps: Professional heatmaps with hierarchical clustering and customizable colormaps.
• MA Plots: Classic M-versus-A plots for global genomic trends.
• Pathway Enrichment: Horizontal bar charts and dynamic Bubble Charts (Gene Count vs. Significance).

📝 Reporting & AI Integration

• Smart Figure Captions: Context-aware, statistically accurate scientific captions generated automatically.
• Comprehensive Reports: Multi-figure assembly into professional PDF and DOCX documents.
• High DPI Standards: All figures are generated at 300 DPI using bbox_inches='tight' for Q1 journal compliance.

---

🛠️ Tech Stack

• Framework: FastMCP
• Libraries: Pandas, Scikit-learn, Scipy, Matplotlib, Seaborn
• Export Formats: PNG (Figures), PDF & DOCX (Reports)

---

🚀 Installation & Claude Integration

BioVis-MCP can be added to Claude Desktop using one of the following methods.

Method 1: Using uvx (Recommended)

This is the fastest way to run BioVis-MCP without manual installation. Ensure you have uv installed.

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "BioVis-MCP": {
      "command": "uvx",
      "args": ["biovis-mcp"]
    }
  }
}

Method 2: Using pip

If you prefer a standard installation:

pip install biovis-mcp

Then add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "BioVis-MCP": {
      "command": "python",
      "args": [
        "-m",
        "biovis_mcp.server"
      ]
    }
  }
}

---

🛠️ Development & Contributing

If you want to contribute or modify the server locally:

1. Clone the Repository

git clone https://github.com/ZaEyAsa/biovis-mcp.git
cd biovis-mcp

2. Install for Development

pip install -e .[dev]

3. Developer Configuration (Claude Desktop)

For local development, point directly to your server.py:

"BioVis-MCP-Dev": {
  "command": "C:/path/to/python.exe",
  "args": [
    "C:/path/to/biovis-mcp/src/biovis_mcp/server.py"
  ],
  "env": {
    "PYTHONPATH": "C:/path/to/biovis-mcp/src"
  }
}

[!TIP] Use absolute paths for both python.exe and server.py on Windows.

---

📖 Available Tools

• generate_volcano_plot(data, title, fc_threshold, pval_threshold)
• generate_bar_enrichment(data, title, top_n, color)
• generate_heatmap_plot(data, title, cluster, cmap)
• generate_pca_plot(data, metadata, title, group_col)
• generate_bubble_enrichment(data, title, top_n)
• generate_ma_plot(data, title, pval_threshold)
• get_figure_caption(tool_type, stats)
• create_report(figures_with_captions, format, report_name)

---

📁 Output Structure

• /figures: High-resolution PNG files.
• /reports: Formatted PDF and DOCX documents.

---

Developed by ZaEyAsa — Your Advanced Agentic Bio-Visualization Assistant.

---

<p align="center"> <b>Built for the global research community, BioVis-MCP transforms how AI assistants interact with biological data. Accelerating discovery, one high-resolution figure at a time.</b> </p>