Stata

通过 Windows Stata Automation COM 让 Claude Code 控制 Stata GUI 的 MCP 服务器。
A Claude Code MCP server that controls the Stata GUI through Windows Stata Automation COM.

中文 | English

---

中文

🎯 核心功能

• 真实 GUI 控制：通过 Stata Automation COM 在已打开的 Stata GUI 窗口中直接运行命令
• Session 会话管理：按 do 文件路径或自定义 session_id 维护独立的 Stata 窗口，同一任务复用同一窗口
• 多窗口支持：不同 do 文件/session_id 自动创建不同 Stata 窗口，方便同时监控多个分析任务
• 灵活命令执行：支持无路径命令自动发送到最近会话，也支持在指定 session 中执行
• 完整 Do 文件管理：写入、读取、追加、运行 do 文件，支持项目本地存储
• 结构化数据获取：读取数据描述、缺失摘要、样本预览、变量标签等，辅助 Claude 精准修改分析代码
• Log 读取与解析：支持读取 Stata text log，可选输出为完整文本、简洁格式或 JSON 命令-结果对
• 安全防护：内置危险命令黑名单，防止意外删除文件或执行 shell 命令
• 任务追踪：本地记录 session、do 文件和 log 的关系，支持任务级别的复现

📺 演示效果

📦 项目结构

D:/Stata18/mcp/
├── README.md                 # 项目文档
├── pyproject.toml           # Python 项目配置
├── .gitignore
├── stata_mcp.py             # 兼容启动器（推荐配置路径）
├── src/
│   └── stata_mcp/
│       ├── __init__.py
│       └── server.py        # MCP 服务器主程序
└── assets/                  # 项目资源

# 运行时自动创建的项目本地缓存（每个项目目录）
project-dir/.stata-mcp/
├── cache/
│   └── task_registry.json   # Session/do/log 关系记录
└── dofiles/                 # 生成的 do 文件

🔧 环境要求

要求	版本	备注
操作系统	Windows	必须。依赖 Windows COM 和 pywin32
Stata	18 MP	须已注册 Automation COM 接口
Python	3.10+	推荐 3.11+
包	mcp, pywin32	通过 pip 安装
Claude 编辑器	Latest	已安装 Claude Code 扩展

📥 安装步骤

1. 克隆或下载项目

推荐放在 Stata 安装目录下的 mcp 文件夹：

# 方式一：克隆到 Stata 目录
cd D:\Stata18
git clone https://github.com/shichengg/stata-mcp mcp

# 方式二：手动下载并解压
# 下载 ZIP 后解压到 D:\Stata18\mcp

高级用户也可放在任意稳定目录，但后续 Claude Code 配置需指向实际 stata_mcp.py 路径。

2. 安装 Python 依赖

推荐方案（使用虚拟环境）：

cd D:\Stata18\mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install mcp pywin32

快速方案（全局安装）：

pip install mcp pywin32

3. 注册 Stata Automation COM

必须以 管理员身份 运行 PowerShell，执行：

Start-Process -FilePath "D:\Stata18\StataMP-64.exe" -ArgumentList "/Register" -Wait

⚠️ 注意：

• 替换 D:\Stata18\StataMP-64.exe 为你的 Stata 安装路径
• 不要在 Git Bash 中运行此命令，因为 Git Bash 可能改写 /Register
• Windows 7/8 用户可能需要禁用 UAC 或使用 runas 命令

4. 验证 COM 接口可用

运行以下命令验证 Stata Automation 是否已正确注册：

python -c "import win32com.client; s = win32com.client.Dispatch('stata.StataOLEApp'); s.DoCommand('display 12345')"

预期结果：Stata GUI 打开或被连接，并在结果窗口显示 12345。

5. 配置 Claude Code

推荐方案（使用 claude mcp add 命令）：

在 PowerShell 中运行以下命令。首先移除旧配置（如有），然后添加新配置：

# 移除旧配置（如果存在）
claude mcp remove stata --scope user

# 标准 Python 环境
claude mcp add stata --scope user -- python D:\Stata18\mcp\stata_mcp.py

如果使用 Conda 环境：

# 移除旧配置
claude mcp remove stata --scope user

# 使用 Conda Python
claude mcp add stata --scope user -- D:/anaconda/python.exe D:\Stata18\mcp\stata_mcp.py

💡 提示：

• 将 D:/anaconda 替换为你的 Conda 安装路径
• 如果 Stata 安装在其他路径，相应调整 D:\Stata18\mcp\stata_mcp.py
• 也可在 Claude Code 中直接运行此命令

配置后重启 Claude Code，确认工具列表中出现 stata MCP。

替代方案（手动编辑 Claude Code 配置）：

如果 claude mcp add 不可用，可手动编辑 Claude Code 的 MCP 配置文件，添加：

"stata": {
  "command": "python",
  "args": ["D:\\Stata18\\mcp\\stata_mcp.py"]
}

💡 配置文件位置：通常在 %APPDATA%\Code\User\settings.json 或通过 Claude Code 的设置界面配置

🌍 环境变量（可选）

通常用户无需设置。如果有特殊需求（如非标准安装路径），可在启动 MCP 前设置以下环境变量：

环境变量	默认值	说明
STATA_MCP_DIR	自动检测项目根目录	MCP 项目目录
STATA_DIR	MCP 上一级目录	Stata 安装目录
STATA_EXE	%STATA_DIR%/StataMP-64.exe	Stata 可执行文件路径
STATA_COM_PROG_ID	stata.StataOLEApp	Stata Automation COM ProgID

示例：

$env:STATA_DIR = "C:\Program Files\Stata18"
$env:STATA_COM_PROG_ID = "stata.StataOLEApp"
python D:\Stata18\mcp\stata_mcp.py

---

📚 工具详解

Stata MCP 服务器提供以下工具供 Claude Code 调用：

核心工具

1. stata_run - 在最近 Session 中执行命令

在最近使用的 Stata 会话中执行一条或多条命令。如果还没有运行过 do 文件，会提示先运行一个。

参数：

• commands (string, required): 要执行的 Stata 命令，多行用换行符分隔

2. stata_run_dofile - 运行 Do 文件（Session 管理）

运行一个 do 文件，并按 do 路径或 session_id 维护独立的 Stata 窗口。

参数：

• path (string, required): do 文件的绝对路径
• session_id (string, optional): 自定义 session ID
• role (string, optional): do 在 session 中的角色 (entry/source/auxiliary)，默认 entry
• log_mode (string, optional): 日志模式 (replace/append)，默认 replace

3. stata_session - 管理 Stata 会话

列出、查询、销毁或切换 Stata 会话。

参数：

• action (string, required): list/get/destroy/set_recent
• session_id (string, optional): session ID

4. stata_write_dofile - 写入 Do 文件

生成并保存 Stata do 文件到磁盘。

参数：

• content (string, required): do 文件内容
• filename (string, optional): 文件名或完整路径

5. stata_read_dofile - 读取 Do 文件

读取 do 文件内容。

参数：

• path (string, required): do 文件的完整路径

6. stata_append_dofile - 追加 Do 文件内容

向已有 do 文件追加代码。

参数：

• path (string, required): do 文件的完整路径
• content (string, required): 要追加的代码

7. stata_read_log - 读取 Stata Log

读取 Stata text log 文件。

参数：

• path (string, optional): log 文件路径，留空则读取最近 session 的日志
• tail_lines (integer, optional): 只读取最后 N 行
• output_format (string, optional): 输出格式 (full/core/dict)，默认 full

8. stata_install_package - 安装包

在 Stata GUI 中安装外部包（如 estout、ivreg2 等）。

参数：

• package (string, required): 包名称
• source (string, optional): 安装来源 (ssc/net)，默认 ssc

9. stata_get_results - 获取存储结果

显示 r() 或 e() 存储结果。

参数：

• type (string, required): 结果类型 (r/e)

10. stata_get_data_info - 查看数据信息

显示当前数据集的基本信息。

11. stata_get_data_schema - 获取数据结构和样本

读取当前数据集结构、缺失摘要和样本预览。

参数：

• sample_rows (integer, optional): 样本预览行数，默认 20
• include_codebook (boolean, optional): 是否包含 codebook，默认 true
• include_sample (boolean, optional): 是否包含样本预览，默认 true
• include_missing (boolean, optional): 是否包含缺失值摘要，默认 true

12. stata_status - 检查服务器状态

查看 MCP 服务器状态和活跃会话。

---

💡 最佳实践

快速数据探索

# 1. 加载数据
stata_run_dofile(path="D:/project/load_data.do", session_id="explore")

# 2. 查看数据结构
stata_get_data_schema(sample_rows=50)

# 3. 运行探索性分析
stata_run(commands="summarize\ncorrelation")

多步骤回归分析

# 1. 数据清洗
stata_run_dofile(path="D:/analysis/01_clean.do", session_id="proj_v1", role="source")

# 2. 主分析
stata_run_dofile(path="D:/analysis/02_model.do", session_id="proj_v1", role="entry")

# 3. 获取系数
stata_get_results(type="e")

调试和迭代

# 首次运行
stata_run_dofile(path="D:/project/analysis.do", session_id="debug_v1")

# 检查结果
stata_read_log(output_format="dict")

# 修改代码
stata_append_dofile(path="D:/project/analysis.do", content="* Fixed: ...")

# 重新运行（同一 session，append 模式）
stata_run_dofile(path="D:/project/analysis.do", session_id="debug_v1", log_mode="append")

---

🔍 故障排查

❌ pywin32 不可用

pip install --upgrade pywin32

❌ COM 无法创建 Stata 实例

以 管理员身份 重新注册 Stata Automation：

Start-Process -FilePath "D:\Stata18\StataMP-64.exe" -ArgumentList "/Register" -Wait

❌ stata_run 提示没有 do 文件会话

先运行一个 do 文件：

stata_run_dofile(path="D:/project/analysis.do")

之后无路径命令会发送到这个最近会话。

❌ Claude 不能看到 Stata GUI 结果

Claude 不能读取屏幕内容。使用以下方案之一：

1. 让 Stata 写 text log，然后通过 stata_read_log 读取
2. 使用 stata_get_data_schema() 读取当前数据结构快照
3. 使用 stata_get_results() 获取存储结果

---

English

🎯 Key Features

• Real GUI Control: Execute commands directly in the active Stata GUI via Stata Automation COM
• Session Management: Maintain independent Stata windows per do-file path or custom session_id
• Multi-Window Support: Different do files/session_ids create separate Stata windows
• Flexible Command Execution: Send pathless commands to recent session or specific session
• Complete Do-File Management: Write, read, append, and run do files with project-local storage
• Structured Data Retrieval: Get data descriptions, missing-value summaries, sample previews
• Log Reading and Parsing: Read Stata text logs in multiple formats (full/clean/JSON)
• Safety Protections: Built-in blacklist for dangerous commands
• Task Tracking: Local records of session/do/log relationships for reproducibility

📺 Demo

📦 Project Structure

D:/Stata18/mcp/
├── README.md                 # Documentation
├── pyproject.toml           # Python configuration
├── .gitignore
├── stata_mcp.py             # Compatibility launcher
├── src/
│   └── stata_mcp/
│       ├── __init__.py
│       └── server.py        # Main MCP server
└── assets/                  # Resources

project-dir/.stata-mcp/
├── cache/
│   └── task_registry.json
└── dofiles/

🔧 Requirements

Requirement	Version	Notes
OS	Windows	Required for Windows COM
Stata	18 MP	Must have Automation COM registered
Python	3.10+	Recommended 3.11+
Packages	mcp, pywin32	Install via pip
Claude Editor	Latest	With Claude Code extension

📥 Installation

1. Clone or Download

cd D:\Stata18
git clone https://github.com/shichengg/stata-mcp mcp

2. Install Dependencies

cd D:\Stata18\mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install mcp pywin32

3. Register Stata Automation COM

Run PowerShell as Administrator:

Start-Process -FilePath "D:\Stata18\StataMP-64.exe" -ArgumentList "/Register" -Wait

4. Verify COM Interface

python -c "import win32com.client; s = win32com.client.Dispatch('stata.StataOLEApp'); s.DoCommand('display 12345')"

5. Configure Claude Code

Run the following commands in PowerShell. First remove old configuration (if exists), then add new configuration:

# Remove old configuration (if it exists)
claude mcp remove stata --scope user

# Standard Python environment
claude mcp add stata --scope user -- python D:\Stata18\mcp\stata_mcp.py

If using Conda environment:

# Remove old configuration
claude mcp remove stata --scope user

# Use Conda Python
claude mcp add stata --scope user -- D:/anaconda/python.exe D:\Stata18\mcp\stata_mcp.py

💡 Tips:

• Replace D:/anaconda with your Conda installation path
• If Stata is installed elsewhere, adjust the path accordingly
• You can also run this command directly in Claude Code

Restart Claude Code and verify stata appears in the MCP tools list.

🌍 Environment Variables (Optional)

Variable	Default	Purpose
STATA_MCP_DIR	Auto-detect	MCP project directory
STATA_DIR	Parent of MCP	Stata installation directory
STATA_EXE	Default path	Stata executable path
STATA_COM_PROG_ID	stata.StataOLEApp	COM ProgID

---

📚 Tools Reference

Stata MCP provides 12 main tools:

1. stata_run - Execute commands in recent session
2. stata_run_dofile - Run do file with session management
3. stata_session - Manage sessions (list/get/destroy/set_recent)
4. stata_write_dofile - Write do file to disk
5. stata_read_dofile - Read do file content
6. stata_append_dofile - Append to do file
7. stata_read_log - Read Stata log file
8. stata_install_package - Install packages (estout, ivreg2, etc.)
9. stata_get_results - Get r() or e() stored results
10. stata_get_data_info - View data info
11. stata_get_data_schema - Get data structure and sample
12. stata_status - Check server status

---

💡 Best Practices

Quick Data Exploration

stata_run_dofile(path="D:/project/load_data.do", session_id="explore")
stata_get_data_schema(sample_rows=50)
stata_run(commands="summarize\ncorrelation")

Multi-Step Regression

stata_run_dofile(path="D:/analysis/01_clean.do", session_id="proj_v1", role="source")
stata_run_dofile(path="D:/analysis/02_model.do", session_id="proj_v1", role="entry")
stata_get_results(type="e")

Debug and Iterate

stata_run_dofile(path="D:/project/analysis.do", session_id="debug_v1")
stata_read_log(output_format="dict")
stata_append_dofile(path="D:/project/analysis.do", content="* Fixed: ...")
stata_run_dofile(path="D:/project/analysis.do", session_id="debug_v1", log_mode="append")

---

🔍 Troubleshooting

❌ pywin32 not available

pip install --upgrade pywin32

❌ Stata COM fails to initialize

Re-register Stata Automation as Administrator:

Start-Process -FilePath "D:\Stata18\StataMP-64.exe" -ArgumentList "/Register" -Wait

❌ "No do file session" error

Run a do file first:

stata_run_dofile(path="D:/project/analysis.do")

❌ Claude can't see Stata results

Use stata_read_log() or stata_get_data_schema():

stata_read_log(output_format="dict")
stata_get_data_schema()

---

📄 License

Open source. See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please open issues and pull requests on GitHub.

---

Repository: github.com/shichengg/stata-mcp

Expected result: the Stata GUI opens or is connected, and displays 12345.

Add to Claude Code (recommended)

Use claude mcp add:

claude mcp add stata -- python D:\Stata18\mcp\stata_mcp.py

If you installed the project somewhere else, replace the path with your actual path. Example:

claude mcp add stata -- python "C:\Program Files\Stata18\mcp\stata_mcp.py"

Restart Claude Code after adding the MCP server, then confirm that the stata tools are available.

Manual Claude Code MCP configuration

If you do not use claude mcp add, you can configure MCP manually with JSON:

"stata": {
  "command": "python",
  "args": ["D:\\Stata18\\mcp\\stata_mcp.py"]
}

You can also point directly to the main server file:

"stata": {
  "command": "python",
  "args": ["D:\\Stata18\\mcp\\src\\stata_mcp\\server.py"]
}

The compatibility launcher stata_mcp.py is usually recommended because it keeps your Claude Code configuration stable if the internal project layout changes later.

Environment variables

Most users do not need these. If your installation path or COM ProgID is unusual, you can configure:

Variable	Default	Purpose
STATA_MCP_DIR	auto-detected project root	MCP project directory
STATA_DIR	parent of MCP directory	Stata installation directory
STATA_EXE	%STATA_DIR%/StataMP-64.exe	used in README registration examples
STATA_COM_PROG_ID	stata.StataOLEApp	Stata Automation ProgID

Tools

Tool	Purpose
stata_run	Run commands in the most recent do-file session
stata_run_dofile	Run/reuse a Stata session by absolute do-file path
stata_write_dofile	Write a do file; simple names go to runtime/dofiles, absolute paths write to that location
stata_read_dofile	Read a do file
stata_append_dofile	Append content to a do file
stata_read_log	Read a Stata text log
stata_install_package	Install external packages in the Stata GUI
stata_get_results	Display return list or ereturn list in the Stata GUI
stata_get_data_info	Display describe in the Stata GUI
stata_get_data_schema	Return current data structure, missing summary, and sample rows to Claude
stata_status	Show MCP and Stata session status

Do-file and session rules

• stata_run_dofile(path) uses the absolute do-file path as the session key.
• The same do-file path reuses the same Stata window.
• Different do-file paths create different Stata windows.
• stata_run, stata_get_results, stata_get_data_info, and stata_get_data_schema are sent to the most recent do-file session by default.
• If no do file has been run yet, pathless commands will ask you to run a do file first.

Reading current data structure and sample rows

stata_get_data_schema creates a text log snapshot in the most recent do-file session and returns it to Claude. By default, it includes:

• describe
• codebook, compact
• misstable summarize
• list in 1/20, abbreviate(20)
• notes
• label dir

Options:

Option	Default	Description
sample_rows	20	Number of sample rows, max 1000
include_codebook	true	Include compact codebook
include_sample	true	Include sample preview
include_missing	true	Include missing-value summary

This lets Claude see not only variable names, types, and labels, but also a small real-data sample, which helps it write better Stata code.

Log strategy

• stata_get_data_schema overwrites its own schema snapshot log because it represents the current data state.
• For other analysis output, ask Stata to write a text log, then use stata_read_log to read it.
• Recommended rule: append within the same Claude/MCP session; overwrite the first time the same do file is run in a new session, so logs do not grow forever.

Troubleshooting

pywin32 is unavailable

Run:

pip install pywin32

COM cannot create a Stata instance

Register Stata Automation again:

Start-Process -FilePath "D:\Stata18\StataMP-64.exe" -ArgumentList "/Register" -Wait

Do not run the /Register command directly in Git Bash, because Git Bash may rewrite /Register as a path.

stata_run says there is no do-file session

Run a do file first:

stata_run_dofile(path="D:/Stata18/mcp/examples/browse_test.do")

After that, pathless commands are sent to the most recent session.

Claude cannot directly see Stata GUI output

Claude cannot read screen contents directly. To let Claude analyze Stata output, write a Stata text log and read it with stata_read_log; or use stata_get_data_schema for a current data snapshot.