Stata MCP 서버

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

中文

기능

• Stata Automation COM을 통해 실제 Stata GUI 창에서 명령을 실행합니다.

• do-file 절대 경로별로 Stata 세션을 유지합니다: 동일한 do-file은 동일한 Stata 창을 재사용합니다.

• 서로 다른 do-file은 서로 다른 Stata 창을 열어 여러 분석 작업을 동시에 쉽게 탐색할 수 있습니다.

• 경로가 없는 명령은 가장 최근에 실행된 do-file 세션으로 전송됩니다.

• do-file 쓰기, 읽기, 추가 및 실행을 지원합니다.

• Claude가 출력 결과를 분석할 수 있도록 Stata 텍스트 로그 읽기를 지원합니다.

• Claude가 do-file을 수정하는 데 도움이 되도록 현재 데이터 구조, 결측치 상황 및 샘플 미리보기를 읽는 기능을 지원합니다.

데모 효과

디렉토리 구조

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. 본 저장소를 다운로드하거나 Stata 설치 디렉토리 아래의 mcp 폴더로 복제(clone)합니다.

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-file 및 세션 규칙

• stata_run_dofile(path)는 do-file 절대 경로를 세션 식별자로 사용합니다.

• 동일한 do-file 경로는 동일한 Stata 창을 재사용합니다.

• 서로 다른 do-file 경로는 서로 다른 Stata 창을 생성합니다.

• stata_run, stata_get_results, stata_get_data_info, stata_get_data_schema는 기본적으로 가장 최근에 실행된 do-file 세션으로 전송됩니다.

• 아직 do-file을 실행한 적이 없는 경우, 경로가 없는 명령은 먼저 do-file을 실행하라는 메시지를 표시합니다.

현재 데이터 구조 및 샘플 읽기

stata_get_data_schema는 최근 do-file 세션에서 텍스트 로그 스냅샷을 생성하고 그 내용을 Claude에게 반환합니다. 기본적으로 다음을 포함합니다:

• describe

• codebook, compact

• misstable summarize

• list in 1/20, abbreviate(20)

• notes

• label dir

선택적 매개변수:

이를 통해 Claude는 변수명, 유형, 라벨뿐만 아니라 실제 데이터의 일부를 볼 수 있어 do-file 수정을 더 정확하게 지원할 수 있습니다.

로그 전략

• stata_get_data_schema는 현재 데이터 구조를 나타내므로 자체 스냅샷 로그를 덮어씁니다.

• 다른 분석 결과는 Claude가 읽어야 할 경우 Stata가 텍스트 로그를 쓰게 한 다음 stata_read_log를 사용하여 읽어야 합니다.

• 권장 규칙: 동일한 Claude/MCP 세션 내에서는 추가(append)하고, 다음 새 세션에서 동일한 do-file을 처음 실행할 때는 덮어써서 로그가 무한히 커지는 것을 방지합니다.

문제 해결

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-file 세션이 없다고 알림

먼저 do-file을 실행하세요:

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

그 후에는 경로가 없는 명령이 이 최근 세션으로 전송됩니다.

Claude가 Stata GUI 결과를 직접 볼 수 없음

Claude는 화면 내용을 읽을 수 없습니다. Stata가 텍스트 로그를 쓰게 한 후 stata_read_log를 통해 읽거나, stata_get_data_schema를 사용하여 현재 데이터 구조 스냅샷을 읽어야 합니다.

Related MCP server: Windows-MCP

English

Features

• Runs Stata commands in the real Stata GUI through Stata Automation COM.

• Keeps one Stata session per absolute do-file path: the same do file reuses the same Stata window.

• Different do files open different Stata windows, so multiple analysis tasks can stay visible.

• Pathless commands are sent to the most recently used do-file session.

• Supports writing, reading, appending, and running do files.

• Supports reading Stata text logs so Claude can analyze command output.

• Supports reading the current data structure, missing-value summary, and sample rows to help Claude edit do files.

Project layout

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

Requirements

• Windows

• Stata 18 MP with Automation COM registered

• Python 3.10+

• Python packages: mcp, pywin32

• Claude Code

Recommended install location

It is recommended to place this project inside your Stata installation directory, for example:

D:/Stata18/mcp

If Stata is installed somewhere else, place the project under that Stata directory, for example:

C:/Program Files/Stata18/mcp

Advanced users may place it in any stable directory. Wherever you install it, the Claude Code MCP configuration must point to the actual stata_mcp.py path.

Installation

1. Download or clone this repository into the mcp folder under your Stata installation directory.

2. Install Python dependencies:

pip install mcp pywin32

You may also use a virtual environment:

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

3. Open PowerShell as Administrator, then register Stata Automation. Adjust the path to your Stata installation:

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

4. Verify COM:

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

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:

Tools

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:

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.