在 Claude Code 里用自然语言做 Stata 分析。你描述要什么，Agent 自己写命令、执行、
读结果、继续下一步 —— 加载数据、清洗、建模、诊断、导出，全在一个持久的 Stata
会话里完成，数据不用反复载入。
一句话，跑完整个分析
你： 加载 auto.dta，用 weight 和 mpg 回归 price，并检查异方差
Agent 自动完成（无需你写任何 Stata 命令）：
stata_use_dataset("auto.dta") → 74 obs, 12 vars 已载入
stata_regress("price", "weight mpg") → R² = 0.293 ; weight 1.75 (p=0.008)
stata_run("estat hettest") → Breusch–Pagan χ² 检验异方差
stata_graph("rvfplot", export="…png") → 残差图导出为文件
数据从第一步起就留在内存里，后面每一步都接着用 —— 这正是 stata_run("regress …")
之外还值得有一个 MCP Server 的原因。
这是什么
两部分组成，一起装进 Claude Code：
- 执行层（MCP Server） —— 经
pystata 直接调用 Stata 的运行时，把 75 个工具
暴露给 Agent。stata_run 执行任意命令、stata_help 查任意命令的官方语法，二者
合起来即「全量内置命令支持」；其余专用工具（回归 / 面板 / IV / 生成变量 / 数据
清洗 / 后估计 / 文件资源 / 后台任务 …）是给高频命令加结构化参数与校验的便利层。
- 知识层（Skill） —— 一份 Stata 编程指南：语法要点、分析模板、常见陷阱、命令
地图与常用外置包。Agent 据此知道该用什么命令，而不是靠猜。
为什么是 pystata，而不是 subprocess
pystata 通过 ctypes 在进程内加载 Stata 运行时，而非每条命令起一个子进程：
- 真会话持久 —— Stata 在 MCP Server 启动时初始化一次，数据集、估计结果、局部
宏在所有工具调用之间保持。多步分析（加载 → 清洗 → 回归 → 诊断）就是自然的对话。
- 低延迟 —— 无进程启动开销，单条命令约 12ms。
- 输出可控 —— 直接读 Stata 输出缓冲；大输出自动分页（
stata_more 翻页），
硬上限 120K 字符防止撑爆 MCP 通道；长命令有 60s 超时看门狗（可显式调大）。
架构
快速开始
前置条件
- Stata：StataNow 19 或 Stata 18+（MP / SE / BE 均可）——需含
utilities/pystata
- Python 3.10+（推荐 3.12+）
- Claude Code 最新版
- 操作系统：Windows 或 macOS（见下方「兼容性」）
一键安装
git clone https://gitea.aliveranme.space/aliveranme/stata-mcp.git
cd stata-mcp
python setup.py
装在非标准位置（如外置卷 /Volumes/xxx/Applications/StataNow）时自动检测会失败 ——
先 export STATA_HOME=/你的/Stata路径 再跑 setup.py 即可。
setup.py 会：检测 Stata 安装（常见路径 + STATA_HOME 环境变量，跨平台）→
创建虚拟环境并安装 fastmcp → 生成 .mcp.json（保留你已有的其他 MCP Server 配置）
→ 验证 Server 可启动。
手动安装（自动检测失败时）
export STATA_HOME="C:/Program Files/StataNow/StataNow19"
export STATA_EDITION=mp
cd mcp-stata-server
uv venv
source .venv/Scripts/activate
uv pip install "fastmcp>=3.2.0"
cd ..
cp .mcp.json.example .mcp.json
通过 npm 安装（无需 clone 仓库）
若你已有 Node.js ≥ 18 与 uv（无 uv 时需 Python 3.10+ 且已装 fastmcp>=3.2.0），可直接使用已发布的
npm 包 @aliveranme/stata-mcp：
export STATA_HOME="/你的/Stata路径"
export STATA_EDITION=mp
npx -y @aliveranme/stata-mcp
Claude Code .mcp.json 配置：
{
"mcpServers": {
"stata": {
"command": "npx",
"args": ["-y", "@aliveranme/stata-mcp"],
"env": { "STATA_HOME": "/Applications/StataNow", "STATA_EDITION": "mp" }
}
}
}
npx @aliveranme/stata-mcp 与 npx stata-mcp-server（bin 名）等价，二者都触发同一个启动器。
连接并验证
重启 Claude Code（或 /reload-plugins），.mcp.json 里的 stata Server 会自动连接。
然后在对话里直接说：
帮我加载 auto.dta 并做描述统计
Agent 会自动走 stata_use_dataset → stata_describe → stata_summarize。
各 Agent 安装教程
除 Claude Code 外，本 MCP 可接入所有支持 MCP 的客户端/Agent。逐平台教程见
docs/agent-setup/：
插件 / 扩展市场分发（Claude Code 插件、Cursor 扩展、Claude Desktop .mcpb）的可行性
评估见 plugin-distribution.md。
MCP 工具（75 个）
能力边界不在工具数量上：stata_run + stata_help 已覆盖全部内置命令。下面的
专用工具是给高频命令加结构化参数与校验的便利层。
| 类别 | 工具 |
|---|
| 核心执行 | stata_run（任意命令，含危险前缀拦截；save_output= 完整输出落盘并登记为资源）· stata_run_do_file（执行前自动拆出 ssc install 单独安装，已装跳过） |
| 数据管理 | stata_use_dataset · stata_import（excel/csv/sas/spss/dbase/parquet）· stata_use_example（sysuse/webuse）· stata_save_dataset · stata_set_cwd · stata_generate · stata_egen · stata_xtset（面板/时序声明） |
| 数据重构 / 校验 | stata_merge · stata_append · stata_reshape · stata_collapse · stata_frame（多数据集）· stata_verify（count/assert/duplicates/isid/missing）· stata_replace · stata_drop · stata_keep · stata_rename · stata_recode · stata_destring |
| 数据探索 | stata_describe · stata_codebook · stata_summarize · stata_list · stata_tabulate · stata_correlate · stata_display |
| 估计 | stata_regress · stata_logistic · stata_probit · stata_poisson · stata_ttest · stata_xtreg · stata_ivregress · stata_logit · stata_mlogit · stata_nbreg · stata_qreg · stata_mixed |
| 后估计 | stata_margins · stata_test · stata_predict · stata_estat（vif/hettest/ovtest/ic）· stata_estimates（存取与并排比较）· stata_lincom · stata_nlcom · stata_hausman · stata_return_list |
| 图形 / 导出 | stata_graph（导出即验证文件写入）· stata_scheme（主题）· stata_export_excel · stata_export_delimited · stata_etable（回归表直出 Word/Excel） |
| 文件资源回传 | stata_list_resources · stata_read_file（info/base64）· stata_register_file —— 导出产物经资源协议（resources/read 读 stata-file:///）取回二进制 |
| 包管理与帮助 | stata_help（查任意命令帮助）· stata_install_package · stata_uninstall_package · stata_describe_package · stata_find_package · stata_list_packages |
| 会话生命周期 | stata_clear（scope 重置）· stata_snapshot（save/list/restore/erase）· stata_more（翻页）· stata_status · stata_ping |
| 长任务控制 | stata_background（后台执行，单块上限 3600s）· stata_task_status · stata_task_cancel · stata_task_result · stata_task_list |
| 服务器日志 | stata_read_log（tail/path） |
各工具的参数与说明
数据管理 — stata_use_dataset 加载 .dta（可只载入子集）；stata_import 覆盖官方
import 命令族，按扩展名推断格式；stata_save_dataset 保存；stata_set_cwd 改工作目录；
stata_generate / stata_egen 创建变量（支持官方 [type] 存储类型与 [if] [in]）；
stata_xtset 声明面板 / 时序结构 —— 它是 stata_xtreg 的前提。
数据探索 — stata_summarize / stata_codebook / stata_list / stata_tabulate
均支持 condition；stata_correlate 可选 pairwise 走 pwcorr；stata_display
算表达式 / 看返回值。
估计 — stata_regress（OLS）、stata_logistic、stata_probit（可选
marginal_effects）、stata_poisson（可选 irr）、stata_ttest（可按组）、
stata_xtreg（effects = fe/re/be/mle/pa，需先 xtset）、stata_ivregress
（2sls/liml/gmm）。扩展族：stata_logit（报告原始系数，OR 用 logistic）、
stata_mlogit（多分类，baseoutcome 定基准）、stata_nbreg（负二项）、
stata_qreg（分位，quantile 默认 0.5）、stata_mixed（多水平，random="|| id:"）。
数据清洗 — stata_replace 覆盖变量值、stata_drop/stata_keep 删/留变量或观测
（两种形态二选一）、stata_rename 重命名（单个或批量）、stata_recode 重编码
（values="(1=0) (2/4=1)" 官方规则组）、stata_destring 字符串转数值（必须
replace=True 或 generate()）。
后估计（须先跑估计命令）— stata_margins（dydx / at）、stata_test
（Wald 检验）、stata_predict（预测值 / 残差，会创建变量）、stata_lincom /
stata_nlcom（线性 / 非线性组合检验）、stata_hausman（模型比较，需先
stata_estimates action="store" 存两个模型）。
图形 / 导出 — stata_graph 把 graph 与 export 原子执行，以文件是否真被写入判定
成败。导出选项按格式自动适配官方边界：尺寸单位（位图与 svg 用像素、pdf 用英寸、
eps/ps/emf 不支持）、quality（仅 jpg）、mag（仅 pdf/eps/ps）、fontface
（仅矢量格式）—— 不适用的选项被丢弃并在返回信息中说明，而非让 Stata 静默失败。
stata_scheme 列出 / 查询 / 设置主题（不传 scheme 时不会改动你当前的主题）。
stata_export_excel 导数据为 .xlsx（支持 sheet_mode / cell / firstrow /
if-in 筛选）；stata_export_delimited 导 CSV / TSV / 自定义分隔符。
回归表用 stata_etable（官方 etable，Stata 17+，无第三方依赖）：
estimates="m1 m2 m3" 并排多模型，直出 .docx / .xlsx / .pdf / .tex / .html / .md，
并以文件是否真被写入判定成败 —— etable 会先把表打印出来再报导出错误，只看输出
很容易把失败当成功。
包管理与帮助 — stata_help("命令") 查任意内置 / 已装外置命令的官方语法；
stata_find_package 走 net search 联网找包；stata_install_package 装（ssc 或 URL）；
stata_uninstall_package 卸载（ado uninstall，纯本地）；stata_describe_package
查包详情（默认本地 ado describe，source="ssc" 走联网 ssc describe 供装前了解）；
stata_list_packages 列已装。
会话 — stata_more 翻上一条命令的完整输出；stata_status 一次给出数据集、工作目录、
frame、面板/时序设定、已存与活跃的估计结果、内存 —— 即 Agent 调 xtreg /
margins / predict 前需要确认的全部前提；stata_ping 心跳。stata_clear 按 scope
重置会话（data/estimates/graphs/panels/all）；stata_snapshot 用 Stata 原生快照在数据
阶段间快速回退（save/list/restore/erase）。
文件资源回传 — 导出工具（stata_graph / stata_export_* / stata_etable /
stata_save_dataset / stata_run save_output=）成功后把文件登记为 MCP 资源。远程
客户端经 resources/read 读 stata-file:///<路径> 取回图表 / Excel / CSV / dta 的
二进制，或 stata_read_file 取 base64 / 元信息；stata_list_resources 列出全部登记
文件，stata_register_file 登记已有的磁盘文件。安全边界：只读登记过的文件。
长任务控制 — stata_background 把耗时长命令放到后台（立即返回任务号，单块超时
上限 3600s，运行期间其他调用会等待共享的 _stata_lock）；stata_task_status 查进度、
stata_task_cancel 显式取消、stata_task_result 取结果、stata_task_list 列全部。
stata_read_log 读本服务器运行日志排查问题。
Stata 知识 Skill
.claude/skills/stata/SKILL.md 是 Agent 的 Stata 编程参考：
| 模块 | 内容 |
|---|
| 核心原则 | 分析前先探数据、变量名大小写、路径规范、返回值检查 |
| 语法要点 | 命令结构、if 条件陷阱、因子变量、循环与条件块、egen 函数 |
| 命令地图 | 3500+ 内置命令按族归类，语法一律指向 stata_help |
| 分析模板 | 数据探索、OLS / Logit、面板、工具变量、DID —— 均经真实 Stata 验证 |
| 外置命令表 | reghdfe / ivreg2 / estout / coefplot / did / rdrobust … 按计量方向组织 |
| 常见陷阱 | 变量名冲突、缺失值、字符串转换、路径、do 文件 |
兼容性
| 组件 | 要求 |
|---|
| Stata | StataNow 19 / Stata 18（MP / SE / BE），需含 utilities/pystata |
| Python | 3.10+ |
| Claude Code | 最新版（支持 MCP stdio） |
| 操作系统 | Windows、macOS（setup.py 跨平台检测；Linux 亦受 setup.py 支持但未实测） |
pystata 是 Stata 官方的 Python 集成，随 Stata 一同分发，Windows / macOS / Linux
均提供。本项目在 Windows 与 macOS（StataNow 19.5 MP）上均实测可用。
配置
环境变量
| 变量 | 默认值 | 说明 |
|---|
STATA_HOME | C:\Program Files\StataNow\StataNow19 | Stata 安装目录。环境变量优先级最高；未设置时由 setup.py 自动检测。 |
STATA_EDITION | mp | Stata 版本（mp / se / be） |
STATA_ALLOWED_ROOTS | 未设置 | 路径沙箱白名单，分号分隔（例 C:/data;D:/projects）。两重限制：未设置时不限制绝对路径；设置后既校验工具的路径参数，也审计 stata_run / stata_run_do_file / stata_background 自由文本命令里的引号路径（use "越界路径" 同样被拒）。宏路径 fail-open，未配置白名单时不启用。 |
STATA_ALLOW_UNC | 未设置 | 设为 1 允许 UNC 网络路径，默认拒绝。 |
JAVA_TOOL_OPTIONS | 自动追加 -Djava.awt.headless=true | MCP 无 GUI 会话时自动启用 Java headless，避免图形导出触发 AWT 渲染错误。若已显式设置 -Djava.awt.headless=true/false，则保留原值。 |
开发 / 调试
cd mcp-stata-server
source .venv/bin/activate
python server.py
python -m pytest tests/ -q
STATA_HOME=/path/to/StataNow python -m pytest tests_e2e/ -q
python -m ruff check server.py tests/ tests_e2e/
python -m ruff check --config pyproject.toml ../setup.py
uv pip install <package>
uv pip freeze > requirements.txt
项目结构
stata-mcp/
├── setup.py # 一键安装（跨平台检测 Stata）
├── mcp-stata-server/
│ ├── server.py # MCP Server 主程序（75 个工具）
│ ├── tool_modules/ # 便利工具模块（数据重构/扩展估计/后估计）
│ ├── tests/ # 单元测试（mock pystata，无需 Stata）
│ └── tests_e2e/ # 端到端测试（需真实 Stata）
├── .claude/skills/stata/SKILL.md # Stata 编程知识 Skill
├── assets/readme/ # README 视觉资产
└── .mcp.json # Server 配置（setup.py 生成）
许可证
MIT License