Docker / GHCR

May 21, 2026 · View on GitHub

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 pathDocker mountPath 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:/outputsgenerated 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

SymptomFix
docker: command not foundInstall Docker Desktop or Docker Engine, then restart your MCP client.
Pull failsCheck the image name and network access with docker pull ghcr.io/cafferychen777/chatspatial:v1.2.10.
MCP tools do not appearUse --rm -i, not -it, and restart the client.
Dataset not foundMount the host data directory and use the container path in prompts, for example /data/sample.h5ad.
Permission denied on outputsConfirm the host output directory exists and Docker has permission to write to it.
Works in terminal but not in the clientUse absolute host paths in -v mounts and restart the client.

Next steps