跳转至

客户端配置

不同的 AI 客户端对 MCP 服务器有不同的配置格式。本文档记录了每个受支持客户端的配置细节。

标准配置模式

大多数 AI 客户端遵循以下基本模式：

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": ["stata-mcp"]
    }
  }
}

但是，每个客户端在文件位置、格式或支持的功能方面可能略有不同。

客户端特定配置

Claude Code

配置方法：CLI 命令或 .mcp.json

全局安装：

claude mcp add stata-mcp -- uvx stata-mcp

基于项目的安装（推荐）：

cd ~/Documents/MyResearch
claude mcp add stata-mcp \
  --env STATA_MCP_CWD=$(pwd) \
  --scope project \
  -- uvx --directory $(pwd) stata-mcp

配置文件：.mcp.json（在项目目录中创建）

格式：JSON

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": ["stata-mcp"],
      "env": {
        "STATA_MCP_CWD": "/absolute/path/to/project"
      }
    }
  }
}

独有功能： - ✅ 项目范围配置（--scope project） - ✅ 环境变量注入（--env） - ✅ 目录指定（--directory） - ✅ 版本固定支持（stata-mcp==1.13.0）

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

格式：JSON

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": ["stata-mcp"],
      "env": {
        "STATA_MCP_CWD": "/path/to/project",
        "STATA_CLI": "/Applications/Stata/StataMP"
      }
    }
  }
}

独有功能： - ✅ 通过 env 对象支持环境变量 - ✅ 需要手动编辑配置文件

Codex（VS Code 扩展）

配置文件：~/.codex/config.toml

格式：TOML

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp"]

带环境变量：

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp"]
env = { STATA_MCP_CWD = "/path/to/project" }

独有功能： - ⚠️ 使用 TOML 格式而非 JSON - ✅ 通过 env 表支持环境变量

Cline

配置文件：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/setting/cline_mcp_settings.json

格式：JSON

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ]
    }
  }
}

独有功能： - ⚠️ 标准 JSON 格式 - ⚠️ 无特殊功能或扩展

Cursor

配置文件：Cursor 设置（位置因操作系统而异）

格式：JSON

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/project",
        "stata-mcp"
      ],
      "env": {
        "STATA_MCP_CWD": "/absolute/path/to/project"
      }
    }
  }
}

已知问题： - ⚠️ 文件系统访问限制（可能无法访问 Documents 目录） - ⚠️ 需要同时在 args 中设置 --directory 和 STATA_MCP_CWD 环境变量（两者必须指向同一路径） - ⚠️ 必须使用绝对路径（不支持相对路径） - ✅ 支持环境变量

Cherry Studio

配置文件：Cherry Studio 设置

格式：JSON（与 Claude Desktop 相同）

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": ["stata-mcp"]
    }
  }
}

独有功能： - ✅ 标准 MCP 配置 - ✅ 与 Claude Desktop 格式兼容

配置选项

命令变体

标准（使用最新版本）：

"command": "uvx",
"args": ["stata-mcp"]

固定版本：

"command": "uvx",
"args": ["stata-mcp==1.13.0"]

带自定义目录：

"command": "uvx",
"args": [
  "--directory",
  "/path/to/project",
  "stata-mcp"
]

环境变量

核心变量

变量 用途 示例
STATA_MCP_CWD Stata 操作的工作目录 "/Users/user/research"
STATA_CLI 特定 Stata 可执行文件路径 "/Applications/Stata/StataMP"
STATA_MCP_MODEL 智能体模式的 LLM 模型 "gpt-4"
STATA_MCP_API_KEY LLM 提供商的 API 密钥 "sk-..."
STATA_MCP_API_BASE_URL 自定义 API 端点 "https://api.openai.com/v1"

安全变量

变量 用途 默认值 示例
STATA_MCP__IS_GUARD 启用安全守卫验证 true "true" 或 "false"

监控变量

变量 用途 默认值 示例
STATA_MCP__IS_MONITOR 启用 RAM 监控 false "true" 或 "false"
STATA_MCP__RAM_LIMIT 最大 RAM（MB） -1（无限制） "8192" 表示 8GB

调试变量

变量 用途 默认值 示例
STATA_MCP__IS_DEBUG 启用调试模式 false "true" 或 "false"
STATA_MCP__LOGGING_ON 启用日志 true "true" 或 "false"
STATA_MCP__LOGGING_CONSOLE_HANDLER_ON 启用控制台日志 false "true" 或 "false"
STATA_MCP__LOGGING_FILE_HANDLER_ON 启用文件日志 true "true" 或 "false"
STATA_MCP__LOG_FILE 自定义日志文件路径 ~/.statamcp/stata_mcp_debug.log "/var/log/stata-mcp/debug.log"

JSON 格式：

"env": {
  "STATA_MCP_CWD": "/path/to/project",
  "STATA_CLI": "/path/to/stata"
}

带安全和监控：

"env": {
  "STATA_MCP_CWD": "/path/to/project",
  "STATA_MCP__IS_GUARD": "true",
  "STATA_MCP__IS_MONITOR": "true",
  "STATA_MCP__RAM_LIMIT": "8192"
}

TOML 格式（Codex）：

env = { STATA_MCP_CWD = "/path/to/project" }

带所有功能：

env.STATA_MCP_CWD = "/path/to/project"
env.STATA_MCP__IS_GUARD = "true"
env.STATA_MCP__IS_MONITOR = "true"
env.STATA_MCP__RAM_LIMIT = "8192"
env.STATA_MCP__LOGGING_CONSOLE_HANDLER_ON = "true"

配置文件位置

客户端 配置文件位置 格式
Claude Code .mcp.json（项目）或全局配置 JSON
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json JSON
Codex ~/.codex/config.toml TOML
Cline ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/setting/cline_mcp_settings.json JSON
Cursor Cursor 设置目录 JSON
Cherry Studio Cherry Studio 设置目录 JSON

故障排除

配置未检测到

  1. 验证文件路径：检查配置文件是否存在于正确位置
  2. 验证 JSON/TOML 语法：使用在线验证器检查语法错误
  3. 重启客户端：大多数客户端在配置更改后需要重启
  4. 检查日志：在客户端日志中查找 MCP 服务器连接错误

路径问题

问题：Stata-MCP 无法访问项目文件

解决方案： - 为 STATA_MCP_CWD 使用绝对路径 - 确保路径在客户端允许的目录内 - 检查客户端的文件系统访问权限

版本冲突

问题：加载了错误的 Stata-MCP 版本

解决方案： - 清除 Python 包缓存：pip cache purge stata-mcp - 固定特定版本：uvx stata-mcp==1.13.0 - 使用 uvx --refresh stata-mcp 强制刷新

最佳实践

  1. 使用项目范围配置（如果可用）（Claude Code）
  2. 在生产环境中固定版本
  3. 为工作目录设置绝对路径
  4. 在添加到客户端之前用 uvx stata-mcp --usable 测试配置
  5. 为团队协作文档化自定义配置

其他资源