配置指南

为你的环境配置 ChatSpatial MCP 服务器。

MCP 客户端配置

Codex（CLI 与 IDE 扩展）

Codex 将 MCP 配置存放在 ~/.codex/config.toml 中。CLI 与 IDE 扩展共用该配置。

通过 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

或直接编辑 ~/.codex/config.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"

高级选项：

[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

要点：

  • 使用 [mcp_servers.chatspatial]（下划线，不是连字符）

  • 配置在 CLI 与 IDE 扩展间共享

  • 在 Codex TUI 中使用 /mcp 验证连接

OpenCode（CLI 与 TUI）

OpenCode 将 MCP 配置存放在：

  • 全局：~/.config/opencode/opencode.json

  • 项目：opencode.json（位于项目根目录）

当两者同时存在时，以项目配置优先。

通过 CLI 添加（向导）：

opencode mcp add
opencode mcp list

或直接编辑配置 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"
      }
    }
  }
}

要点：

  • 使用 which python 输出的 绝对 Python 路径

  • command 是一个数组：[executable, ...args]

  • 如果你希望使用仓库级设置，优先使用项目级 opencode.json

  • 文档：https://opencode.ai/docs/mcp

Claude Desktop

编辑 Claude Desktop 配置文件：

位置：

  • 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"]
    }
  }
}

实际路径示例：

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

**重要：**修改配置后重启 Claude Desktop。

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. **找到 Python 路径：**激活虚拟环境并运行 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.

环境变量（可选）

使用环境变量配置 ChatSpatial 行为：

数据存储

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

**用途：**当你使用 export_data() 且未指定 path 时，数据集会保存到该目录。

**默认：**在原始数据文件旁的 .chatspatial_saved/

配置故障排查

常见问题

问题

解决方案

“找不到 python”

使用虚拟环境 Python 的完整路径

“找不到模块”

添加服务器前确保已激活虚拟环境

Claude 无法连接

检查 JSON 语法并重启 Claude Desktop

服务器未显示

用 which python 验证 Python 路径是否正确

验证配置

# 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

下一步