ChatSpatial
MCP server for spatial transcriptomics analysis via natural language
Add to your client
Copy the config for your MCP client and paste it into its config file.
uv pip install chatspatialPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"chatspatial": {
"command": "/path/to/venv/bin/python",
"args": [
"-m",
"chatspatial",
"server"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.11-3.13 (3.12 recommended)
- 8GB+ RAM (16GB+ for large datasets)
- An MCP-compatible client (Claude Code, Claude Desktop, Codex, OpenCode)
- uv recommended for dependency resolution (large scientific Python stack)
- Docker only if using the containerized runtime
- R >= 4.4 on PATH for the 'full' extra (R-backed methods)
About ChatSpatial
ChatSpatial replaces ad-hoc LLM code generation with schema-enforced orchestration for spatial transcriptomics. The LLM selects tools and parameters from a curated registry of 20 MCP tools that orchestrate 65 analysis methods across 15 categories — data loading and preprocessing, visualization, spatial domain identification, deconvolution, cell-cell communication, cell type annotation, differential expression, trajectory inference, RNA velocity, spatial statistics, enrichment analysis, spatially variable genes, multi-sample integration, CNV analysis, and spatial registration. It supports 10x Visium, Xenium, Slide-seq v2, MERFISH, and seqFISH. The server can run from a local Python environment (Python 3.11-3.13) or a Docker image from GHCR, and it works with any MCP-compatible client.
Tools & capabilities (20)
load_dataLoad spatial transcriptomics data (H5AD, 10X Visium folders, H5, MTX) for visium, xenium, slide_seq, merfish, seqfish, or generic types.
preprocess_dataNormalize, filter, and prepare data (normalization, HVG selection, PCA, neighbor graph, QC filtering, optional doublet detection).
compute_embeddingsCompute dimensionality reduction and clustering (PCA, UMAP, Leiden clustering, spatial neighbor graph).
export_dataExport a dataset to disk for use by external scripts (default ~/.chatspatial/active/{data_id}.h5ad).
reload_dataReload a dataset after external modifications.
analyze_spatial_statisticsAnalyze spatial patterns and autocorrelation (Moran's I, Local Moran, Geary's C, Getis-Ord Gi*, Ripley's K, co-occurrence, neighborhood enrichment, centrality scores, and more).
find_spatial_genesIdentify spatially variable genes using methods such as SpatialDE, SPARK-X, and FlashS.
identify_spatial_domainsIdentify spatial domains using SpaGCN, STAGATE, GraphST, BANKSY, Leiden, or Louvain.
annotate_cell_typesAnnotate cell types using Tangram, scANVI, CellAssign, mLLMCelltype, scType, or SingleR.
deconvolve_dataDeconvolve spot composition using FlashDeconv, Cell2location, RCTD, DestVI, Stereoscope, SPOTlight, Tangram, or CARD.
analyze_cell_communicationAnalyze cell-cell communication using LIANA+, CellPhoneDB, CellChat (cellchat_r), or FastCCC.
find_markersFind marker genes (Wilcoxon, t-test, logistic regression).
compare_conditionsRun differential expression across conditions (including pyDESeq2).
analyze_enrichmentRun enrichment analysis (GSEA, ORA, Enrichr, ssGSEA, Spatial EnrichMap).
analyze_velocity_dataCompute RNA velocity using scVelo or VeloVI.
analyze_trajectory_dataInfer cellular trajectories using CellRank, Palantir, or DPT.
analyze_cnvAnalyze copy number variation using InferCNVPy or Numbat.
integrate_samplesIntegrate multiple samples using Harmony, BBKNN, Scanorama, or scVI.
register_spatial_dataRegister/align spatial datasets using PASTE or STalign.
visualize_dataGenerate spatial plots, embedding plots, and gene expression overlays.
What this server can do
ChatSpatial provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Run a full spatial transcriptomics workflow (load, QC, normalize, cluster, visualize) through natural-language prompts
- Identify spatial domains and spatially variable genes across Visium, Xenium, Slide-seq, MERFISH, or seqFISH data
- Deconvolve spot-level composition and annotate cell types using established reference-based methods
- Analyze cell-cell communication, trajectories, RNA velocity, and CNV from a single conversational interface
- Produce reproducible, schema-validated analyses that behave consistently across MCP clients and sessions
Security notes
Runs locally over stdio and reads spatial-omics data files from absolute host paths passed to load_data. When using the Docker image, host data is mounted read-only at /data and outputs at /outputs; prompts must reference container paths. No API keys or network credentials are required by the server itself.
ChatSpatial FAQ
Which MCP clients does ChatSpatial work with?
Any MCP-compatible client. The docs give explicit configuration for Claude Code, Claude Desktop, Codex, and OpenCode, plus a generic pattern for other clients.
How do I install it?
Install from PyPI with 'uv pip install chatspatial' (uv is recommended because of the large scientific stack), then configure your MCP client to run '/path/to/venv/bin/python -m chatspatial server'. A Docker image is also available at ghcr.io/cafferychen777/chatspatial.
How do I point it at my data?
Pass an absolute host path to load_data (e.g. /Users/alice/spatial/sample.h5ad). There is no global search directory, so keep paths explicit. With Docker, mount host data to /data read-only and use container paths like /data/sample.h5ad.
What's the difference between tools and methods?
ChatSpatial exposes 20 schema-validated MCP tools as the stable interface. Each tool orchestrates one or more of the 65 underlying analysis methods, which are selected via parameters like method, analysis_type, plot_type, or subtype.
Alternatives to ChatSpatial
Compare all alternatives →
Official MCP server providing persistent, file-backed knowledge-graph memory across sessions.
Structured step-by-step reasoning tool for breaking problems into revisable thought sequences.
Fully managed remote server for AWS docs, blogs, What's-New and Well-Architected guidance — no key.
Compare ChatSpatial with: