CLI 参考
Stata-MCP 提供命令行界面（CLI）用于各种操作，包括启动 MCP 服务器、运行智能体模式以及安装到不同的 AI 客户端。
安装
验证您的安装：
stata-mcp --version
运行诊断检查系统健康状况：
stata-mcp doctor
注意：
--usable自 v1.14.3 起已弃用，将在 v1.16.0 中移除。请改用stata-mcp doctor。
命令
启动 MCP 服务器
使用不同的传输方式启动 MCP 服务器：
# 使用 stdio 传输启动（默认）
stata-mcp
# 明确指定传输方式
stata-mcp -t stdio
stata-mcp -t sse
stata-mcp -t http
Server 子命令
使用 server 子命令控制注册哪些 MCP 工具：
# 所有工具，stdio 传输（与裸命令相同）
stata-mcp server
# 仅核心工具（stata_do、get_data_info、help）
stata-mcp server --core
# 所有工具，HTTP 传输
stata-mcp server --all -t http
# 核心工具，SSE 传输
stata-mcp server --core -t sse
工具配置（Profile）：
- --all - 注册所有可用工具（默认）
- --core - 仅注册核心工具：stata_do、get_data_info、help
传输选项：
- stdio - 标准输入/输出（默认）
- sse - Server-Sent Events
- http - HTTP 传输（自动转换为 streamable-http）
智能体模式
以交互式智能体模式运行 Stata-MCP：
# 在当前目录启动智能体
stata-mcp agent run
# 在指定目录启动智能体
stata-mcp agent run --work-dir /path/to/project
本地工具命令
诊断检查（doctor）
运行健康检查以诊断潜在问题：
# 运行所有检查
stata-mcp doctor
# 显示每项检查的详细信息
stata-mcp doctor --verbose
# 以 JSON 格式输出
stata-mcp doctor --json
# 仅运行特定检查（可重复）
stata-mcp doctor --check stata --check python
更新（update）
将 stata-mcp 更新到最新版本：
# 自动检测安装方式并更新
stata-mcp update
# 检查是否有新版本可用
stata-mcp update --check
# 显示检测到的方式和可用更新但不执行
stata-mcp update --dry-run
# 强制指定更新方式
stata-mcp update --method pip # pip install
stata-mcp update --method uv-tool # uv tool upgrade
stata-mcp update --method homebrew # brew upgrade
更新方式： auto（默认）、pip、uv-tool、homebrew
本地工具命令
直接从 CLI 运行由 API 模块驱动的 Stata 工具：
# 从 SSC 安装 ado 包（默认源）
stata-mcp tool ado-install reghdfe
# 运行 do-file 并打印生成的日志输出
stata-mcp tool do /path/to/analysis.do
# 通过一次性的 API helper 读取 Stata help
stata-mcp tool help regress --is-read-log true --enable-smcl true
# 查看支持的数据集元信息
stata-mcp tool data-info /path/to/data.dta
# 读取生成的日志文件
stata-mcp tool read-log /path/to/output.log
工具子命令：
- stata-mcp tool ado-install <package_name> [--source ssc|net|github]
- stata-mcp tool do <dofile_path> [--is-read-log true|false] [--enable-smcl true|false]
- stata-mcp tool help <command> [--is-read-log true|false] [--enable-smcl true|false]
- stata-mcp tool data-info <data_path> [--vars-list var1 var2 ...]
- stata-mcp tool read-log <log_path> [--output-format full|core|dict]
配置管理
查看和更新本地 CLI 配置：
# 打印当前配置文件内容（~/.statamcp/config.toml）
stata-mcp config
# 手动设置 STATA_CLI 路径
stata-mcp config cli set /path/to/stata
# 自动检测 STATA_CLI 并持久化保存
stata-mcp config cli set
安装到 AI 客户端
将 Stata-MCP 安装到各种 AI 编程助手：
# 安装到 Claude Desktop（默认）
stata-mcp install
# 安装到特定客户端
stata-mcp install -c claude # Claude Desktop
stata-mcp install -c cc # Claude Code
stata-mcp install -c gemini # Gemini CLI
stata-mcp install -c cursor # Cursor
stata-mcp install -c cline # Cline
stata-mcp install -c codex # Codex
stata-mcp install -c opencode # OpenCode
# 安装到所有支持的客户端
stata-mcp install --all
# 安装到自定义配置文件
stata-mcp install --json-file /path/to/config.json
支持的客户端：
- claude - Claude Desktop
- cc - Claude Code
- gemini - Gemini CLI
- cursor - Cursor Editor
- cline - Cline（VS Code 扩展）
- codex - Codex
- opencode - OpenCode
基于 Docker 的安装（sandbox-install）
将基于 Docker 的 Stata-MCP 安装到 AI 客户端。需要 Docker 和有效的 Stata 许可证。
# 使用默认设置的基本用法（StataNow 19.5 MP）
uvx stata-mcp sandbox-install -l /path/to/stata.lic
# 指定 Stata 版本和版本类型
uvx stata-mcp sandbox-install \
--version 19_5 \
--edition mp \
-l /path/to/stata.lic \
-c claude
# 带资源限制
uvx stata-mcp sandbox-install \
-V 18 \
-e se \
-l /path/to/stata.lic \
--cpus 2 \
--memory 4g
Stata 版本： 19_5、18_5、18
Stata 版本类型： mp（多处理器）、se（标准版）、be（基础版）
选项
Server 选项
| 选项 | 描述 |
|---|---|
--core |
仅注册核心工具（stata_do、get_data_info、help） |
--all |
注册所有工具（默认） |
--transport |
-t |
全局选项
| 选项 | 简写 | 描述 |
|---|---|---|
--version |
-v |
显示版本信息 |
--help |
-h |
显示帮助信息 |
--usable |
-u |
（已弃用） 检查系统兼容性，请改用 stata-mcp doctor |
--transport |
-t |
MCP 传输方式（stdio/sse/http） |
智能体选项
| 选项 | 描述 |
|---|---|
--work-dir |
智能体的工作目录（默认：当前目录） |
配置选项
| 命令 | 描述 |
|---|---|
stata-mcp config |
打印原始配置文件内容 |
stata-mcp config cli set [value] |
设置 STATA.STATA_CLI，省略 value 时自动检测 |
安装选项
| 选项 | 简写 | 描述 |
|---|---|---|
--client |
-c |
目标客户端（默认：claude） |
--all |
-a |
安装到所有支持的客户端 |
--json-file |
自定义目标客户端配置文件路径 |
诊断选项（doctor）
| 选项 | 描述 |
|---|---|
--verbose |
显示每项检查的详细信息 |
--json |
以 JSON 格式输出报告 |
--check |
仅运行指定检查（可重复） |
更新选项（update）
| 选项 | 描述 |
|---|---|
--method |
强制指定更新方式（auto/pip/uv-tool/homebrew） |
--dry-run |
显示检测到的方式但不执行更新 |
--check |
仅检查是否有新版本可用 |
Sandbox-Install 选项
| 选项 | 简写 | 默认值 | 描述 |
|---|---|---|---|
--version |
-V |
19_5 |
Stata 版本（19_5, 18_5, 18） |
--edition |
-e |
mp |
Stata 版本类型（mp, se, be） |
--tag |
latest |
Docker 镜像标签 | |
--license-file |
-l |
（必填） | Stata 许可证文件路径 |
--client |
-c |
claude |
目标客户端 |
--work-dir |
./ |
工作目录 | |
--cpus |
（无） | CPU 核心限制 | |
--memory |
（无） | 内存限制（如 4g） |
示例
基本用法
# 检查 Stata-MCP 能否在您的系统上运行
stata-mcp doctor
# 为 Claude Desktop 启动 MCP 服务器
stata-mcp
# 使用 SSE 传输启动
stata-mcp -t sse
开发工作流程
# 1. 运行诊断检查
stata-mcp doctor
# 2. 安装到 Claude Desktop
stata-mcp install
# 3. 运行智能体进行交互式分析
stata-mcp agent run
使用 uvx
如果您不想全局安装 Stata-MCP，可以使用 uvx：
# 检查版本
uvx stata-mcp --version
# 运行诊断
uvx stata-mcp doctor
# 运行智能体
uvx stata-mcp agent run
# 安装到客户端
uvx stata-mcp install -c cursor
退出代码
0- 成功1- 错误（无效客户端、系统不兼容等）2- 命令行参数错误
环境变量
Stata-MCP 的行为可以通过环境变量配置。详见配置。
关键环境变量：
STATA_MCP_CWD- Stata 操作的工作目录STATA_MCP_LOGGING_ON- 启用/禁用日志STATA_MCP__IS_GUARD- 启用安全守卫验证STATA_MCP__IS_MONITOR- 启用 RAM 监控
完整列表请参见配置文档。
故障排除
"Stata not found" 错误
确保 Stata 已安装并可访问：
stata-mcp doctor
这将运行诊断检查并确认 Stata 是否能在您的系统上找到。
权限错误
某些操作可能需要适当的权限： - 安装到 Claude Desktop 可能需要管理员/用户权限 - 工作目录必须可写
传输问题
如果遇到特定传输方式的问题：
- 大多数用例默认使用 stdio
- 如果自动检测失败，明确使用 --transport stdio