Configuration Guide

Configure ChatSpatial MCP server for your environment.

MCP Client Configuration

Codex (CLI and IDE Extension)

Codex stores MCP configuration in ~/.codex/config.toml. The CLI and IDE extension share this configuration.

Add via CLI:

# Find your virtual environment Python path
source venv/bin/activate
which python
# Copy the output path

# Add ChatSpatial MCP server
codex mcp add chatspatial -- /path/to/venv/bin/python -m chatspatial server

# Verify in Codex TUI
/mcp

Or edit ~/.codex/config.toml directly:

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

# Optional: Environment variables
[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    # Default: 10
tool_timeout_sec = 120      # Default: 60
enabled = true              # Set to false to disable without deleting

Key points:

  • Use [mcp_servers.chatspatial] (underscore, not hyphen)

  • Configuration is shared between CLI and IDE extension

  • Use /mcp in Codex TUI to verify connection

OpenCode (CLI and TUI)

OpenCode stores MCP configuration in:

  • Global: ~/.config/opencode/opencode.json

  • Project: opencode.json (in your project root)

Project config takes precedence when both exist.

Add via CLI (wizard):

opencode mcp add
opencode mcp list

Or edit config JSON directly (recommended for repeatability):

{
  "$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"
      }
    }
  }
}

Key points:

  • Use the absolute Python path from which python

  • command is an array: [executable, ...args]

  • Prefer project-level opencode.json if you want repo-specific settings

  • Docs: https://opencode.ai/docs/mcp

Claude Desktop

Edit Claude Desktop configuration file:

Location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

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

Example with actual path:

{
  "mcpServers": {
    "chatspatial": {
      "command": "/Users/yourname/Projects/venv/bin/python",
      "args": ["-m", "chatspatial", "server"]
    }
  }
}

Important: Restart Claude Desktop after configuration changes.

Other MCP Clients (Qwen, DeepSeek, Doubao, etc.)

ChatSpatial is an MCP server that works with any MCP-compatible client — not limited to Claude/Anthropic.

Using OpenCode with other LLMs:

OpenCode supports multiple LLM providers. You can use ChatSpatial with Qwen, DeepSeek, Doubao, or any other supported model:

  1. Install OpenCode and configure your preferred LLM as the backend

  2. Add ChatSpatial as an MCP server (see OpenCode section above)

  3. Start analyzing with your chosen LLM

For any MCP-compatible client:

  1. Find Python path: Activate virtual environment and run which python

  2. Configure MCP server: Use command /path/to/venv/bin/python -m chatspatial server

The key requirement is MCP support, not a specific LLM provider.

Environment Variables (Optional)

Configure ChatSpatial behavior using environment variables:

Data Storage

# Set custom data directory for saved datasets
export CHATSPATIAL_DATA_DIR="/path/to/your/spatial/data"

Usage: When you use export_data() without specifying path, datasets are saved to this directory.

Default: .chatspatial_saved/ next to original data file

Troubleshooting Configuration

Common Issues

Problem

Solution

“python not found”

Use full path to virtual environment Python

“module not found”

Ensure virtual environment is activated before adding server

Claude can’t connect

Check JSON syntax and restart Claude Desktop

Server not showing up

Verify Python path is correct with which python

Verify Configuration

# Make sure you're in the virtual environment
which python
# Should show virtual environment path, not system Python

# Test ChatSpatial import
python -c "import chatspatial; print(f'ChatSpatial {chatspatial.__version__} ready')"

# Test MCP server
python -m chatspatial server --help
# Should display server options

Next Steps