ChatSpatial

Agentic Workflow Orchestration for Spatial Transcriptomics Analysis

Eliminate the implementation tax. Focus on biological insight.

ChatSpatial is an agentic workflow orchestration platform that integrates 60 state-of-the-art methods from fragmented Python and R ecosystems into a unified conversational interface. Built on the Model Context Protocol (MCP), it enables human-steered discovery through natural language in Claude Desktop or Claude Code, eliminating the need for manual data conversion and complex programming.

🎯 Example: Analyze spatial transcriptomics data through conversation with Claude

👤 "Load my 10x Visium dataset and identify spatial domains"
🤖 ✅ Loaded 3,456 spots, 18,078 genes
    ✅ Identified 7 spatial domains using SpaGCN
    ✅ Generated spatial domain visualization

👤 "Find marker genes for domain 3 and create a heatmap"
🤖 ✅ Found 23 significant markers (adj. p < 0.05)
    ✅ Top markers: GFAP, S100B, AQP4 (astrocyte signature)
    ✅ Generated expression heatmap

👤 = You chatting with Claude | 🤖 = ChatSpatial MCP executing analysis

🚀 Why Researchers Choose ChatSpatial

# 50+ lines of code for basic analysis
import scanpy as sc
import squidpy as sq
import pandas as pd
import matplotlib.pyplot as plt

adata = sc.read_h5ad("data.h5ad")
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
# ... 40+ more lines ...

"Analyze my Visium data and find
 spatially variable genes"

⚡ Quick Start (2 Minutes)

1. Create Virtual Environment & Install

# Clone and enter directory
git clone https://github.com/cafferychen777/ChatSpatial.git
cd chatspatial

# Create virtual environment (strongly recommended)
# For macOS with Homebrew Python:
/opt/homebrew/bin/python3.10 -m venv chatspatial_env  # macOS Homebrew
# For other systems:
# python3 -m venv chatspatial_env  # Linux/other systems
source chatspatial_env/bin/activate  # macOS/Linux
# chatspatial_env\Scripts\activate  # Windows

# Verify Python version and install
python --version  # Should be 3.10+
pip install --upgrade pip
pip install -e ".[full]"  # Recommended: All features included

💡 Windows Users: SingleR and PETSc acceleration are not available on Windows due to C++ compilation limitations. Use alternative cell type annotation methods (Tangram, scANVI, CellAssign). All R-based methods (RCTD, SPOTlight, Numbat) work on Windows. See INSTALLATION.md for details.

2. Configure Your Client

{
  "mcpServers": {
    "chatspatial": {
      "command": "/path/to/chatspatial_env/bin/python",
      "args": ["-m", "chatspatial", "server"]
    }
  }
}

npm install -g @anthropic-ai/claude-code

# First, activate your virtual environment
source chatspatial_env/bin/activate

# Then get the exact Python path (copy this output!)
which python

# Replace <PYTHON_PATH_FROM_STEP_2> with the actual path from step 2
claude mcp add chatspatial <PYTHON_PATH_FROM_STEP_2> -- -m chatspatial server

# Example with real path:
# claude mcp add chatspatial /Users/yourname/Research/chatspatial_env/bin/python -- -m chatspatial server

claude mcp list

# IMPORTANT: Exit and restart Claude Code for changes to take effect
/quit

# Then re-enter Claude Code
claude

3. Download Sample Data & Start Analyzing

🎯 Quick Test (1 minute):

1. Download sample datasets: Go to ChatSpatial Releases
2. Download these files:
   • card_reference_filtered.h5ad (36MB - pancreatic reference with 9 cell types)
   • card_spatial.h5ad (7.7MB - spatial data with clear tissue domains)

3. Open Claude Desktop or Claude Code and chat with ChatSpatial:

💡 Important: Tell Claude to use ChatSpatial MCP for your spatial analysis (e.g., "Use ChatSpatial MCP for all my spatial transcriptomics analysis"). This ensures Claude calls the MCP tools instead of writing scripts.

Simply type this natural language request in your Claude chat:

Load /Users/yourname/Downloads/card_reference_filtered.h5ad and /Users/yourname/Downloads/card_spatial.h5ad, then show me the tissue structure

💡 How it works: ChatSpatial MCP server interprets your natural language and automatically calls the appropriate analysis tools. No coding required!

⚠️ IMPORTANT: Use absolute paths when loading data (e.g., /Users/yourname/Downloads/card_reference_filtered.h5ad)

🎯 That's it! ChatSpatial will load your data and create a beautiful spatial visualization - all through natural language conversation.

📚 Detailed Setup Guides: Claude Desktop | Claude Code

🧬 What You Can Do

💬 All examples below are natural language commands you type in Claude chat with ChatSpatial MCP

📊 Try These Examples (After Loading Sample Data)

Chat with Claude using these natural language requests:

Identify spatial domains using SpaGCN

Deconvolve the spatial data using the reference with Cell2location

Analyze cell communication between spatial regions

Find spatially variable genes and create heatmaps

What happens: ChatSpatial MCP automatically selects the right tools, runs the analysis, and returns publication-ready visualizations.

🔍 Spatial Analysis - Just Ask in Plain English

🧮 Advanced Methods - No Coding Knowledge Required

🎨 Instant Visualizations

• Spatial plots with tissue overlays
• Interactive heatmaps for gene expression
• Communication networks between cell types
• Trajectory flow maps for development
• Domain boundary visualizations

🎯 Choose Your Path

pip install -e .

pip install -e ".[full]"

pip install -e ".[dev]"

🛠️ Technical Capabilities

🤝 Community & Support

• 📧 Issues: GitHub Issues for bug reports
• 📖 Docs: Complete documentation with tutorials
• ⭐ Star this repo to follow development

📄 License & Citation

MIT License - Free for academic and commercial use.

If ChatSpatial helps your research, please cite:

@software{chatspatial2025,
  title={ChatSpatial: An Agentic Framework for Reproducible Cross-Platform Spatial Transcriptomics Analysis},
  author={Chen Yang and Xianyang Zhang and Jun Chen},
  year={2025},
  url={https://github.com/cafferychen777/ChatSpatial},
  note={Manuscript in preparation}
}

🙏 Built With

ChatSpatial stands on the shoulders of giants: Scanpy • Squidpy • scvi-tools • LIANA • Anthropic MCP