Configuration Guide¶

This page is the canonical reference for exact MCP client configuration syntax.

To install ChatSpatial, see Installation.
To run your first workflow after setup, see Quick Start.
If configuration fails, see Troubleshooting.

Configuration Workflow¶

Install ChatSpatial in a virtual environment.
Activate the environment and run which python.
Use that absolute Python path in your MCP client config.
Restart the client after configuration changes.
Verify the server can start.

Canonical command shape:

/absolute/path/to/python -m chatspatial server

Claude Code (Recommended)¶

source venv/bin/activate
which python
claude mcp add chatspatial /path/to/venv/bin/python -- -m chatspatial server
claude mcp list

Notes:

-- separates the Python path from module arguments
use the absolute Python path from which python
use --scope user if you want the server available across projects

Codex¶

Codex stores MCP configuration in ~/.codex/config.toml.

Add via CLI¶

source venv/bin/activate
which python
codex mcp add chatspatial -- /path/to/venv/bin/python -m chatspatial server

Or edit config directly¶

[mcp_servers.chatspatial]
command = "/path/to/venv/bin/python"
args = ["-m", "chatspatial", "server"]

[mcp_servers.chatspatial.env]
CHATSPATIAL_DATA_DIR = "/path/to/data"

Advanced options¶

[mcp_servers.chatspatial]
command = "/path/to/venv/bin/python"
args = ["-m", "chatspatial", "server"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

OpenCode¶

OpenCode stores MCP configuration in:

global: ~/.config/opencode/opencode.json
project: opencode.json

Project config takes precedence when both exist.

Add via CLI¶

opencode mcp add
opencode mcp list

Or edit config directly¶

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chatspatial": {
      "type": "local",
      "command": ["/path/to/venv/bin/python", "-m", "chatspatial", "server"],
      "enabled": true,
      "environment": {
        "CHATSPATIAL_DATA_DIR": "/path/to/data"
      }
    }
  }
}

Notes:

command is an array: [executable, ...args]
use the absolute Python path from which python
prefer project-level config for repo-specific settings

Claude Desktop¶

Edit the Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop after saving the file.

Other MCP Clients¶

ChatSpatial works with any MCP-compatible client.

Minimum requirement:

configure the executable as your environment’s Python
pass -m chatspatial server as arguments

Use the same absolute Python path pattern shown above.

Environment Variables¶

Data storage¶

export CHATSPATIAL_DATA_DIR="/path/to/your/spatial/data"

When export_data() is called without an explicit path, ChatSpatial saves to this directory.

Default behavior: .chatspatial_saved/ next to the original data file.

Verify Configuration¶

which python
python -c "import chatspatial; print(f'ChatSpatial {chatspatial.__version__} ready')"
python -m chatspatial server --help

If these checks fail, use Troubleshooting.

Next Steps¶

Quick Start — first successful analysis
Troubleshooting — fix configuration or runtime issues
Methods Reference — exact parameters and defaults