Docker / GHCR

Use the Docker image when you want to run ChatSpatial without resolving the scientific Python dependency stack on your host machine.

This is the canonical Docker runtime guide. Other pages may remind you to use container paths such as /data/sample.h5ad, but Docker image tags, mounts, --rm -i, /outputs, SSE mode, and Docker-specific failures are maintained here.

Image

ghcr.io/cafferychen777/chatspatial:v1.2.10

This guide uses the versioned v1.2.10 tag so commands are reproducible. Use :latest only when you explicitly want the newest published image.

Pull and verify the image

docker pull ghcr.io/cafferychen777/chatspatial:v1.2.10
docker run --rm ghcr.io/cafferychen777/chatspatial:v1.2.10 --version
docker run --rm ghcr.io/cafferychen777/chatspatial:v1.2.10 server --help

Run as an MCP server

Use this command shape in MCP clients that support Docker-backed stdio servers:

docker run --rm -i \
  -v /absolute/path/to/your/data:/data:ro \
  -v /absolute/path/to/outputs:/outputs \
  ghcr.io/cafferychen777/chatspatial:v1.2.10 server --transport stdio

Use --rm -i, not -it, for MCP stdio. A TTY can corrupt the JSON-RPC stream used by MCP clients.

Mount data and outputs

ChatSpatial runs inside the container. It cannot see host files unless they are mounted into the container.

Host path

Docker mount

Path to use in prompts

/Users/alice/spatial-data

-v /Users/alice/spatial-data:/data:ro

/data/sample.h5ad

/home/alice/chatspatial-outputs

-v /home/alice/chatspatial-outputs:/outputs

generated files appear under /outputs

If your host data directory is mounted as /data, prompt ChatSpatial with /data/sample.h5ad, not the original host path.

Generated visualizations are written under /outputs by default. If you call export_data() without an explicit path, it uses ~/.chatspatial/active/{data_id}.h5ad inside the container; pass a path under /outputs when the exported file should persist after the container exits.

MCP client examples

Claude Code

claude mcp add chatspatial-docker docker -- \
  run --rm -i \
  -v /absolute/path/to/your/data:/data:ro \
  -v /absolute/path/to/outputs:/outputs \
  ghcr.io/cafferychen777/chatspatial:v1.2.10 server --transport stdio

Claude Desktop

{
  "mcpServers": {
    "chatspatial": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/your/data:/data:ro",
        "-v",
        "/absolute/path/to/outputs:/outputs",
        "ghcr.io/cafferychen777/chatspatial:v1.2.10",
        "server",
        "--transport",
        "stdio"
      ]
    }
  }
}

Restart your MCP client after changing configuration.

SSE server

docker run --rm -p 8000:8000 \
  -v /absolute/path/to/your/data:/data:ro \
  -v /absolute/path/to/outputs:/outputs \
  ghcr.io/cafferychen777/chatspatial:v1.2.10 server --transport sse --host 0.0.0.0 --port 8000

Then connect your MCP client to http://localhost:8000/sse.

Build locally from source

From the repository root:

docker build -t chatspatial:local .

Then replace ghcr.io/cafferychen777/chatspatial:v1.2.10 with chatspatial:local in the commands above.

Common Docker issues

Symptom

Fix

docker: command not found

Install Docker Desktop or Docker Engine, then restart your MCP client.

Pull fails

Check the image name and network access with docker pull ghcr.io/cafferychen777/chatspatial:v1.2.10.

MCP tools do not appear

Use --rm -i, not -it, and restart the client.

Dataset not found

Mount the host data directory and use the container path in prompts, for example /data/sample.h5ad.

Permission denied on outputs

Confirm the host output directory exists and Docker has permission to write to it.

Works in terminal but not in the client

Use absolute host paths in -v mounts and restart the client.

Next steps