ChatSpatial

1<div align="center">
2 
3# ChatSpatial
4 
5**MCP server for spatial transcriptomics analysis via natural language**
6 
7[![CI](https://github.com/cafferychen777/ChatSpatial/actions/workflows/ci.yml/badge.svg)](https://github.com/cafferychen777/ChatSpatial/actions/workflows/ci.yml)
8[![PyPI](https://img.shields.io/pypi/v/chatspatial)](https://pypi.org/project/chatspatial/)
9[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
10[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11[![Docs](https://img.shields.io/badge/docs-available-blue)](https://cafferychen777.github.io/ChatSpatial/)
12 
13</div>
14 
15---
16 
17<table>
18<tr>
19<td width="50%">
20 
21### Before
22```python
23import scanpy as sc
24import squidpy as sq
25adata = sc.read_h5ad("data.h5ad")
26sc.pp.filter_cells(adata, min_genes=200)
27sc.pp.normalize_total(adata)
28sc.pp.log1p(adata)
29sc.pp.highly_variable_genes(adata)
30sc.tl.pca(adata)
31sc.pp.neighbors(adata)
32# ... 40 more lines
33```
34 
35</td>
36<td width="50%">
37 
38### After
39```text
40"Load my Visium data and identify
41 spatial domains"
42```
43 
44```
45Loaded 3,456 spots, 18,078 genes
46Identified 7 spatial domains
47Generated visualization
48```
49 
50</td>
51</tr>
52</table>
53 
54---
55 
56## Quick Start
57 
58**Using Claude Code / Codex / OpenCode?** Just paste this:
59```
60Install ChatSpatial following https://github.com/cafferychen777/ChatSpatial/blob/main/INSTALLATION.md
61```
62 
63<details>
64<summary>Manual installation</summary>
65 
66```bash
67# Install uv (recommended - handles complex dependencies)
68curl -LsSf https://astral.sh/uv/install.sh | sh
69 
70# Create environment and install
71python3 -m venv venv && source venv/bin/activate
72uv pip install chatspatial
73 
74# Configure (use your venv Python path)
75claude mcp add chatspatial /path/to/venv/bin/python -- -m chatspatial server
76```
77</details>
78 
79> **Works with any MCP-compatible client** — not just Claude. Use with [OpenCode](https://opencode.ai/), Codex, or any client supporting [Model Context Protocol](https://modelcontextprotocol.io/). Configure your preferred LLM (Qwen, DeepSeek, Doubao, etc.) as the backend.
80 
81See [Installation Guide](INSTALLATION.md) for detailed setup including virtual environments and all MCP clients.
82 
83---
84 
85## Use
86 
87```text
88Load /path/to/spatial_data.h5ad and show me the tissue structure
89```
90 
91```text
92Identify spatial domains using SpaGCN
93```
94 
95```text
96Find spatially variable genes and create a heatmap
97```
98 
99---
100 
101## Capabilities
102 
103| Category | Methods |
104|----------|---------|
105| **Spatial Domains** | SpaGCN, STAGATE, GraphST, Leiden, Louvain |
106| **Deconvolution** | FlashDeconv, Cell2location, RCTD, DestVI, Stereoscope, SPOTlight, Tangram, CARD |
107| **Cell Communication** | LIANA+, CellPhoneDB, CellChat, FastCCC |
108| **Cell Type Annotation** | Tangram, scANVI, CellAssign, mLLMCelltype, scType, SingleR |
109| **Trajectory & Velocity** | CellRank, Palantir, DPT, scVelo, VeloVI |
110| **Spatial Statistics** | Moran's I, Local Moran, Geary's C, Getis-Ord Gi*, Ripley's K, Neighborhood Enrichment |
111| **Enrichment** | GSEA, ORA, Enrichr, ssGSEA, Spatial EnrichMap |
112| **Spatial Genes** | SpatialDE, SPARK-X |
113| **Integration** | Harmony, BBKNN, Scanorama, scVI |
114| **Other** | CNV Analysis, Spatial Registration |
115 
116**60+ methods** across 15 categories. **Supports** 10x Visium, Xenium, Slide-seq v2, MERFISH, seqFISH.
117 
118---
119 
120## Documentation
121 
122| Guide | Description |
123|-------|-------------|
124| [Installation](INSTALLATION.md) | Virtual environment setup, all platforms |
125| [Quick Start](docs/quickstart.md) | 5-minute first analysis |
126| [Examples](docs/examples.md) | Step-by-step workflows |
127| [Methods Reference](docs/advanced/methods-reference.md) | All 20 tools with parameters |
128| [Full Docs](https://cafferychen777.github.io/ChatSpatial/) | Complete reference |
129 
130---
131 
132## Citation
133 
134```bibtex
135@software{chatspatial2025,
136  title={ChatSpatial: Agentic Workflow for Spatial Transcriptomics},
137  author={Chen Yang and Xianyang Zhang and Jun Chen},
138  year={2025},
139  url={https://github.com/cafferychen777/ChatSpatial}
140}
141```
142 
143<div align="center">
144 
145**MIT License** · [GitHub](https://github.com/cafferychen777/ChatSpatial) · [Issues](https://github.com/cafferychen777/ChatSpatial/issues)
146 
147</div>
148 
149<!-- mcp-name: io.github.cafferychen777/chatspatial -->
150