How to add ChatSpatial to Claude Desktop

MCP server for spatial transcriptomics analysis via natural language Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 40★ · stdio · no auth

Claude Desktop config for ChatSpatial

uv pip install chatspatial

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

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the ChatSpatial config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm ChatSpatial's tools appear under the 🔌 tools menu.

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)

What ChatSpatial can do in Claude Desktop

load_data

Load spatial transcriptomics data (H5AD, 10X Visium folders, H5, MTX) for visium, xenium, slide_seq, merfish, seqfish, or generic types.

preprocess_data

Normalize, filter, and prepare data (normalization, HVG selection, PCA, neighbor graph, QC filtering, optional doublet detection).

compute_embeddings

Compute dimensionality reduction and clustering (PCA, UMAP, Leiden clustering, spatial neighbor graph).

export_data

Export a dataset to disk for use by external scripts (default ~/.chatspatial/active/{data_id}.h5ad).

reload_data

Reload a dataset after external modifications.

analyze_spatial_statistics

Analyze 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_genes

Identify spatially variable genes using methods such as SpatialDE, SPARK-X, and FlashS.

identify_spatial_domains

Identify spatial domains using SpaGCN, STAGATE, GraphST, BANKSY, Leiden, or Louvain.

Security

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the ChatSpatial config there under the "mcpServers" key and restart the client.

Is ChatSpatial safe to use with Claude Desktop?

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.

View repo Full ChatSpatial page