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