Servidor MCP de Stata

Un servidor MCP que permite a Claude Code controlar la GUI de Stata a través de Windows Stata Automation COM.

• 中文

• English

中文

功能

• 通过 Stata Automation COM 在真实 Stata GUI 窗口中运行命令。

• 按 do 文件绝对路径维护 Stata 会话：同一个 do 文件复用同一个 Stata 窗口。

• 不同 do 文件打开不同 Stata 窗口，方便同时浏览多个分析任务。

• 不带路径的命令会发送到最近一次运行的 do 文件会话。

• 支持 do 文件写入、读取、追加和运行。

• 支持读取 Stata text log，供 Claude 分析输出结果。

• 支持读取当前数据结构、缺失情况和样本预览，辅助 Claude 修改 do 文件。

演示效果

目录结构

D:/Stata18/mcp/
├── README.md
├── pyproject.toml
├── .gitignore
├── stata_mcp.py              # 兼容启动器
├── src/
│   └── stata_mcp/
│       ├── __init__.py
│       └── server.py         # MCP 服务器主文件
├── runtime/
│   ├── dofiles/              # Claude/MCP 默认生成 do 文件
│   └── logs/                 # Claude/MCP 默认读取或生成 log
└── examples/                 # 示例 do 文件

环境要求

• Windows

• Stata 18 MP，已注册 Automation COM

• Python 3.10+

• Python 包：mcp, pywin32

• Claude Code

推荐安装位置

推荐把本项目放在 Stata 安装目录下的 mcp 文件夹，例如：

D:/Stata18/mcp

如果 Stata 安装在其他位置，也建议放在对应目录下，例如：

C:/Program Files/Stata18/mcp

高级用户也可以放在任意稳定目录。无论放在哪里，Claude Code MCP 配置中的脚本路径都必须指向实际的 stata_mcp.py。

安装步骤

1. 下载或 clone 本仓库到 Stata 安装目录下的 mcp 文件夹。

2. 安装 Python 依赖：

pip install mcp pywin32

也可以在虚拟环境中安装：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install mcp pywin32

3. 以管理员身份打开 PowerShell，注册 Stata Automation。按你的 Stata 安装路径修改命令：

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

4. 验证 COM 是否可用：

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

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

添加到 Claude Code（推荐）

推荐使用 claude mcp add：

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

如果安装在其他路径，请替换为实际路径。例如：

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

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

手动配置 Claude Code MCP

如果不使用 claude mcp add，也可以手动配置 MCP JSON：

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

也可以直接指向主文件：

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

通常建议使用兼容启动器 stata_mcp.py，这样后续项目内部结构调整时配置更稳定。

可配置环境变量

一般用户不需要设置。如果你的安装路径或 COM 名称特殊，可以设置：

工具

do 文件和会话规则

• stata_run_dofile(path) 使用 do 文件绝对路径作为会话标识。

• 同一个 do 文件路径会复用同一个 Stata 窗口。

• 不同 do 文件路径会创建不同 Stata 窗口。

• stata_run、stata_get_results、stata_get_data_info、stata_get_data_schema 默认发送到最近一次运行的 do 文件会话。

• 如果还没有运行过 do 文件，无路径命令会提示先运行一个 do 文件。

读取当前数据结构和样本

stata_get_data_schema 会在最近 do 文件会话中生成一份 text log 快照，并把内容返回给 Claude。默认包含：

• describe

• codebook, compact

• misstable summarize

• list in 1/20, abbreviate(20)

• notes

• label dir

可选参数：

这让 Claude 不仅能看到变量名、类型和标签，还能看到少量真实数据，从而更准确地辅助修改 do 文件。

Log 策略

• stata_get_data_schema 会覆盖生成自己的 schema 快照 log，因为它表示当前数据结构。

• 其他分析结果需要 Claude 读取时，应让 Stata 写 text log，然后使用 stata_read_log 读取。

• 推荐规则：同一 Claude/MCP 会话内追加；下次新会话首次运行同一 do 文件时覆盖，避免 log 无限增长。

故障排查

pywin32 不可用

运行：

pip install pywin32

COM 无法创建 Stata 实例

重新注册 Stata Automation：

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

不要在 Git Bash 中直接运行带 /Register 的命令，因为 Git Bash 可能把 /Register 改写成路径。

stata_run 提示还没有 do 文件会话

先运行一个 do 文件：

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

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

Claude 不能直接看到 Stata GUI 结果

Claude 不能读取屏幕内容。需要让 Stata 写 text log，然后通过 stata_read_log 读取；或者使用 stata_get_data_schema 读取当前数据结构快照。

Related MCP server: Windows-MCP

English

Características

• Ejecuta comandos de Stata en la GUI real de Stata a través de Stata Automation COM.

• Mantiene una sesión de Stata por cada ruta absoluta de archivo do: el mismo archivo do reutiliza la misma ventana de Stata.

• Diferentes archivos do abren diferentes ventanas de Stata, por lo que se pueden mantener visibles múltiples tareas de análisis.

• Los comandos sin ruta se envían a la sesión de archivo do utilizada más recientemente.

• Admite escribir, leer, añadir y ejecutar archivos do.

• Admite la lectura de registros de texto (logs) de Stata para que Claude pueda analizar la salida de los comandos.

• Admite la lectura de la estructura de datos actual, el resumen de valores faltantes y filas de muestra para ayudar a Claude a editar archivos do.

Diseño del proyecto

D:/Stata18/mcp/
├── README.md
├── pyproject.toml
├── .gitignore
├── stata_mcp.py              # compatibility launcher
├── src/
│   └── stata_mcp/
│       ├── __init__.py
│       └── server.py         # main MCP server
├── runtime/
│   ├── dofiles/              # default do files generated by Claude/MCP
│   └── logs/                 # default logs generated or read by Claude/MCP
└── examples/                 # example do files

Requisitos

• Windows

• Stata 18 MP con Automation COM registrado

• Python 3.10+

• Paquetes de Python: mcp, pywin32

• Claude Code

Ubicación de instalación recomendada

Se recomienda colocar este proyecto dentro del directorio de instalación de Stata, por ejemplo:

D:/Stata18/mcp

Si Stata está instalado en otro lugar, coloque el proyecto bajo ese directorio de Stata, por ejemplo:

C:/Program Files/Stata18/mcp

Los usuarios avanzados pueden colocarlo en cualquier directorio estable. Dondequiera que lo instale, la configuración de Claude Code MCP debe apuntar a la ruta real de stata_mcp.py.

Instalación

1. Descargue o clone este repositorio en la carpeta mcp bajo el directorio de instalación de Stata.

2. Instale las dependencias de Python:

pip install mcp pywin32

También puede usar un entorno virtual:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install mcp pywin32

3. Abra PowerShell como Administrador y luego registre Stata Automation. Ajuste la ruta a su instalación de Stata:

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

4. Verifique COM:

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

Resultado esperado: la GUI de Stata se abre o se conecta y muestra 12345.

Agregar a Claude Code (recomendado)

Use claude mcp add:

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

Si instaló el proyecto en otro lugar, reemplace la ruta con su ruta real. Ejemplo:

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

Reinicie Claude Code después de agregar el servidor MCP y luego confirme que las herramientas stata están disponibles.

Configuración manual de Claude Code MCP

Si no usa claude mcp add, puede configurar MCP manualmente con JSON:

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

También puede apuntar directamente al archivo principal del servidor:

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

El lanzador de compatibilidad stata_mcp.py suele ser recomendable porque mantiene estable su configuración de Claude Code si el diseño interno del proyecto cambia más adelante.

Variables de entorno

La mayoría de los usuarios no las necesita. Si su ruta de instalación o ProgID de COM es inusual, puede configurar:

Herramientas

Reglas de archivos do y sesiones

• stata_run_dofile(path) utiliza la ruta absoluta del archivo do como clave de sesión.

• La misma ruta de archivo do reutiliza la misma ventana de Stata.

• Diferentes rutas de archivo do crean diferentes ventanas de Stata.

• stata_run, stata_get_results, stata_get_data_info y stata_get_data_schema se envían a la sesión de archivo do más reciente de forma predeterminada.

• Si aún no se ha ejecutado ningún archivo do, los comandos sin ruta le pedirán que ejecute un archivo do primero.

Lectura de la estructura de datos actual y filas de muestra

stata_get_data_schema crea una instantánea de registro de texto en la sesión de archivo do más reciente y la devuelve a Claude. De forma predeterminada, incluye:

• describe

• codebook, compact

• misstable summarize

• list in 1/20, abbreviate(20)

• notes

• label dir

Opciones:

Esto permite a Claude ver no solo los nombres, tipos y etiquetas de las variables, sino también una pequeña muestra de datos reales, lo que le ayuda a escribir mejor código de Stata.

Estrategia de registro (Log)

• stata_get_data_schema sobrescribe su propio registro de instantánea de esquema porque representa el estado actual de los datos.

• Para otras salidas de análisis, pida a Stata que escriba un registro de texto y luego use stata_read_log para leerlo.

• Regla recomendada: añadir dentro de la misma sesión de Claude/MCP; sobrescribir la primera vez que se ejecuta el mismo archivo do en una nueva sesión, para que los registros no crezcan indefinidamente.

Solución de problemas

pywin32 no está disponible

Ejecute:

pip install pywin32

COM no puede crear una instancia de Stata

Registre Stata Automation de nuevo:

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

No ejecute el comando /Register directamente en Git Bash, porque Git Bash puede reescribir /Register como una ruta.

stata_run dice que no hay sesión de archivo do

Ejecute un archivo do primero:

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

Después de eso, los comandos sin ruta se envían a la sesión más reciente.

Claude no puede ver directamente la salida de la GUI de Stata

Claude no puede leer el contenido de la pantalla directamente. Para que Claude analice la salida de Stata, escriba un registro de texto de Stata y léalo con stata_read_log; o use stata_get_data_schema para una instantánea de los datos actuales.