ChatSpatial replaces ad-hoc LLM code generation with schema-enforced orchestration. Instead of generating arbitrary scripts, the LLM selects tools and parameters from a curated registry, making spatial transcriptomics workflows more reproducible across sessions and clients.

ChatSpatial exposes 20 schema-validated MCP tools that orchestrate 66 spatial transcriptomics methods across 15 analytical categories. The tools are the stable natural-language interface; the methods are the analysis backends selected through tool parameters.

The server implements MCP 2026-07-28 through the official Python SDK v2 and continues to serve 2025-11-25 clients through SDK-managed protocol negotiation. STDIO remains the secure local default; Streamable HTTP is available for explicitly configured HTTP deployments.

Start Here

Install uv once, then register ChatSpatial without creating or managing a Python environment:

Codex:

codex mcp add chatspatial -- uvx --from chatspatial chatspatial server

Claude Code:

claude mcp add --scope user chatspatial -- \
  uvx --from chatspatial chatspatial server

uvx creates an isolated environment on first launch and reuses its cache on later launches. Restart the MCP client after adding the server.

Then:

1. Run your first analysis — Quick Start
2. Choose optional method families or a persistent environment — Installation Guide
3. Configure another MCP client — Configuration Guide
4. Inspect or reproduce the manuscript results — Reproducibility workspace

Docker quick start:

docker pull ghcr.io/cafferychen777/chatspatial:v1.3.2

Minimal example prompt:

Load /absolute/path/to/spatial_data.h5ad and show me the tissue structure

If you use Docker, mount host data to /data and prompt with the container path, for example /data/spatial_data.h5ad.

ChatSpatial works with any MCP-compatible client — Claude Code, Claude Desktop, Codex, OpenCode, and other MCP-capable tools.

Capabilities

Current coverage includes 66 methods across 15 analytical categories, exposed through 20 MCP tools. Supports 10x Visium, Xenium, Slide-seq v2, MERFISH, seqFISH.

Documentation

Reproducibility

The manuscript experiment scripts, small aggregate result tables, and supplementary tables are versioned in reproducibility/. Large datasets, raw provider checkpoints, generated analysis directories, and manuscript source files are intentionally kept outside Git. The reproducibility workspace documents both the manuscript-era package baseline and the current-checkout development workflow so historical evidence is not silently regenerated with a different ChatSpatial release.

Citation

If you use ChatSpatial in your research, please cite:

@article{Yang2026.02.26.708361,
  author = {Yang, Chen and Zhang, Xianyang and Chen, Jun},
  title = {ChatSpatial: Schema-Enforced Agentic Orchestration for Reproducible and Cross-Platform Spatial Transcriptomics},
  elocation-id = {2026.02.26.708361},
  year = {2026},
  doi = {10.64898/2026.02.26.708361},
  publisher = {Cold Spring Harbor Laboratory},
  URL = {https://www.biorxiv.org/content/early/2026/03/01/2026.02.26.708361},
  journal = {bioRxiv}
}

ChatSpatial orchestrates many excellent third-party methods. Please also cite the original tools your analysis used.

Contributing

Documentation improvements, bug reports, and new analysis methods are all welcome. See CONTRIBUTING.md.