# ChatSpatial Installation
## Step 1: Create Virtual Environment
```bash
# Python 3.11+ required
python3 -m venv venv
source venv/bin/activate # macOS/Linux
# venv\Scripts\activate # Windows
# Or use conda
conda create -n chatspatial python=3.12
conda activate chatspatial
```
## Step 2: Install
**Recommended: Use `uv` for fast, reliable installation**
```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install ChatSpatial
uv pip install chatspatial[full]
```
> **Why uv?** ChatSpatial has complex bioinformatics dependencies (squidpy, scanpy, scvi-tools, spatialdata). Standard `pip` may fail with `resolution-too-deep` errors. `uv` has a more powerful resolver that handles this seamlessly.
<details>
<summary>Alternative: pip (may fail on complex dependency trees)</summary>
```bash
pip install --upgrade pip
pip install chatspatial[full]
```
If you see `resolution-too-deep` error, switch to `uv`.
</details>
| Option | Command | Features |
|--------|---------|----------|
| **Full** | `uv pip install chatspatial[full]` | All 60+ methods |
| Standard | `uv pip install chatspatial` | Core methods |
## Step 3: Configure MCP Client
ChatSpatial works with **any MCP-compatible client** — not limited to Claude/Anthropic.
```bash
# Get your Python path
which python # e.g., /Users/you/venv/bin/python
# Claude Code
claude mcp add chatspatial /path/to/venv/bin/python -- -m chatspatial server
# OpenCode (supports Qwen, DeepSeek, Doubao, etc.)
# See: https://github.com/opencode-ai/opencode
opencode mcp add
# Codex
codex mcp add chatspatial -- /path/to/venv/bin/python -m chatspatial server
```
**Other clients:** See [Configuration Guide](docs/advanced/configuration.md) for Claude Desktop, OpenCode with custom LLMs, and advanced options.
## Step 4: Verify
```bash
python -c "import chatspatial; print('Ready')"
```
Restart your client, then see [Quick Start](docs/quickstart.md) to begin analyzing.
---
## Requirements
- **Python 3.11+** (3.12 recommended)
- **8GB+ RAM** (16GB+ for large datasets)
- **macOS, Linux, or Windows**
---
## Platform Notes
### Windows
**Not available:** SingleR, PETSc
**Use instead:** Tangram, scANVI, CellAssign for annotation; CellRank works without PETSc.
### Python Version Error
If you see `mcp>=1.17.0 not found`:
```bash
rm -rf venv
python3.12 -m venv venv
source venv/bin/activate
pip install chatspatial[full]
```
---
## Optional Dependencies
### R Methods
For RCTD, SPOTlight, CARD, scType, Numbat:
```bash
# Install R 4.4+ from https://cran.r-project.org/
Rscript install_r_dependencies.R
```
### STAGATE
```bash
git clone https://github.com/QIFEIDKN/STAGATE_pyG.git
cd STAGATE_pyG && python setup.py install
```
---
## Help
- [Configuration Guide](docs/advanced/configuration.md) — MCP client setup
- [Troubleshooting](docs/advanced/troubleshooting.md) — Common issues
- [GitHub Issues](https://github.com/cafferychen777/ChatSpatial/issues)
