# Configuration Guide
Configure ChatSpatial MCP server for your environment.
---
## MCP Client Configuration
### Claude Code (Recommended)
```bash
# Find your virtual environment Python path
source venv/bin/activate
which python
# Copy the output path
# Add ChatSpatial MCP server
claude mcp add chatspatial /path/to/venv/bin/python -- -m chatspatial server
# Verify connection
claude mcp list
# Should show: chatspatial: ... - Connected
```
**Key points:**
- The `--` separates the Python path from the module arguments
- Always use absolute path from `which python`
- Use `--scope user` to make ChatSpatial available across all projects
---
### Codex (CLI and IDE Extension)
Codex stores MCP configuration in `~/.codex/config.toml`. The CLI and IDE extension share this configuration.
**Add via CLI:**
```bash
# 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:**
```toml
[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:**
```toml
[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):**
```bash
opencode mcp add
opencode mcp list
```
**Or edit config JSON directly (recommended for repeatability):**
```json
{
"$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:**
```json
{
"mcpServers": {
"chatspatial": {
"command": "/path/to/venv/bin/python",
"args": ["-m", "chatspatial", "server"]
}
}
}
```
**Example with actual path:**
```json
{
"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](https://opencode.ai/) 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
```bash
# 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
```bash
# 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
- [Quick Start](../quickstart.md) - Start analyzing data
- [Troubleshooting](troubleshooting.md) - Solve common problems
- [Methods Reference](methods-reference.md) - Explore available tools
